Share gradient stop calculations with Kotlin Multiplatform

Author: kunal26das

.github/workflows/test-all.yml

@@ -41,8 +41,8 @@ jobs:
     if: github.repository == 'react/react-native'
     outputs:
       any_code_change: ${{ steps.filter_exclusions.outputs.any_code_change == 'true' || github.event_name != 'pull_request' }}
-      should_test_android: ${{ steps.filter_exclusions.outputs.should_test_android == 'true' || github.event_name != 'pull_request' }}
-      should_test_ios: ${{ steps.filter_exclusions.outputs.should_test_ios == 'true' || github.event_name != 'pull_request' }}
+      should_test_android: ${{ steps.filter_exclusions.outputs.should_test_android == 'true' || steps.filter_inclusions.outputs.react_shared == 'true' || github.event_name != 'pull_request' }}
+      should_test_ios: ${{ steps.filter_exclusions.outputs.should_test_ios == 'true' || steps.filter_inclusions.outputs.react_shared == 'true' || github.event_name != 'pull_request' }}
       debugger_shell: ${{ steps.filter_inclusions.outputs.debugger_shell }}
     steps:
       - name: Checkout
@@ -85,6 +85,9 @@ jobs:
         id: filter_inclusions
         with:
           filters: |
+            # Shared Kotlin and its build configuration affect both platforms.
+            react_shared:
+              - 'packages/react-native/ReactShared/**'
             debugger_shell:
               - 'packages/debugger-shell/**'
               - 'scripts/debugger-shell/**'

.github/workflows/test-kmp.yml

@@ -0,0 +1,109 @@
+name: Test Kotlin Multiplatform pilot
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - '.github/workflows/test-kmp.yml'
+      - '.github/actions/setup-gradle/**'
+      - '.github/actions/setup-xcode/**'
+      - 'Gemfile'
+      - 'Gemfile.lock'
+      - 'settings.gradle.kts'
+      - 'packages/react-native/ReactShared/**'
+      - 'packages/react-native/ReactAndroid/build.gradle.kts'
+      - 'packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/ColorStop.kt'
+      - 'packages/react-native/ReactAndroid/src/test/java/com/facebook/react/uimanager/style/ColorStopTest.kt'
+      - 'packages/react-native/React/Fabric/Utils/RCTGradientUtils.*'
+      - 'packages/react-native/React/React-RCTFabric.podspec'
+      - 'packages/react-native/scripts/react_native_pods.rb'
+      - 'packages/react-native/scripts/cocoapods/kmp.rb'
+      - 'packages/react-native/Package.swift'
+      - 'packages/react-native/package.json'
+      - 'packages/react-native/settings.gradle.kts'
+  push:
+    branches:
+      - main
+      - '*-stable'
+    paths:
+      - '.github/workflows/test-kmp.yml'
+      - '.github/actions/setup-gradle/**'
+      - '.github/actions/setup-xcode/**'
+      - 'Gemfile'
+      - 'Gemfile.lock'
+      - 'settings.gradle.kts'
+      - 'packages/react-native/ReactShared/**'
+      - 'packages/react-native/ReactAndroid/build.gradle.kts'
+      - 'packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/ColorStop.kt'
+      - 'packages/react-native/ReactAndroid/src/test/java/com/facebook/react/uimanager/style/ColorStopTest.kt'
+      - 'packages/react-native/React/Fabric/Utils/RCTGradientUtils.*'
+      - 'packages/react-native/React/React-RCTFabric.podspec'
+      - 'packages/react-native/scripts/react_native_pods.rb'
+      - 'packages/react-native/scripts/cocoapods/kmp.rb'
+      - 'packages/react-native/Package.swift'
+      - 'packages/react-native/package.json'
+      - 'packages/react-native/settings.gradle.kts'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: kmp-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test-shared:
+    runs-on: macos-26
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Set up JDK 17
+        uses: actions/setup-java@v5
+        with:
+          java-version: '17'
+          distribution: 'zulu'
+      - name: Set up Xcode for Kotlin Native
+        uses: ./.github/actions/setup-xcode
+        with:
+          xcode-version: '26.4.1'
+      - name: Set up Gradle
+        uses: ./.github/actions/setup-gradle
+      - name: Set up Ruby and CocoaPods
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2.0'
+          bundler-cache: true
+      - name: Check CocoaPods linking configurations
+        run: bundle exec ruby packages/react-native/ReactShared/scripts/test-cocoapods-linking.rb
+      - name: Cache Kotlin Native toolchain
+        uses: actions/cache@v5
+        with:
+          path: ~/.konan
+          key: kmp-native-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('packages/react-native/ReactShared/*.gradle.kts', 'packages/react-native/ReactShared/gradle.properties', 'packages/react-native/ReactShared/gradle/wrapper/gradle-wrapper.properties') }}
+      - name: Test shared code on JVM and iOS
+        working-directory: packages/react-native/ReactShared
+        run: >-
+          ./gradlew
+          jvmTest iosSimulatorArm64Test
+          linkDebugFrameworkIosArm64 linkReleaseFrameworkIosArm64
+          linkDebugFrameworkIosSimulatorArm64 linkReleaseFrameworkIosSimulatorArm64
+          linkDebugFrameworkIosX64 linkReleaseFrameworkIosX64
+          --stacktrace --console=plain
+      - name: Compare the Apple adapter with native gradients
+        working-directory: packages/react-native/ReactShared
+        run: ./scripts/test-apple-gradient.sh
+      - name: Compare optimized Apple gradients
+        working-directory: packages/react-native/ReactShared
+        env:
+          RCT_KMP_BUILD_TYPE: Release
+        run: ./scripts/test-apple-gradient.sh
+      - name: Upload test reports
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: kotlin-multiplatform-test-results
+          path: |
+            packages/react-native/ReactShared/build/reports/tests
+            packages/react-native/ReactShared/build/test-results
+          if-no-files-found: warn

build.gradle.kts

@@ -72,6 +72,7 @@ nexusPublishing {
 tasks.register("clean", Delete::class.java) {
   description = "Remove all the build files and intermediate build outputs"
   dependsOn(gradle.includedBuild("gradle-plugin").task(":clean"))
+  dependsOn(gradle.includedBuild("react-native-shared").task(":clean"))
   subprojects.forEach {
     if (
         it.project.plugins.hasPlugin("com.android.library") ||
@@ -103,6 +104,7 @@ tasks.register("clean", Delete::class.java) {
 tasks.register("build") {
   description = "Build and test all the React Native relevant projects."
   dependsOn(gradle.includedBuild("gradle-plugin").task(":build"))
+  dependsOn(gradle.includedBuild("react-native-shared").task(":jvmTest"))
 }
 
 tasks.register("publishAllToMavenTempLocal") {

packages/react-native/Package.swift

@@ -9,6 +9,10 @@
 import Foundation
 import PackageDescription
 
+if ProcessInfo.processInfo.environment["RCT_USE_KMP"] == "1" {
+  fatalError("RCT_USE_KMP=1 currently supports CocoaPods source builds only. Run RCT_USE_KMP=1 pod install in the iOS app; the SwiftPM prebuild does not include ReactNativeShared.")
+}
+
 let BUILD_FROM_SOURCE = false
 
 // Removing the legacy TurboModule and component interop layers is opt-in while those

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

@@ -8,10 +8,18 @@
 #import "RCTGradientUtils.h"
 #import <React/RCTAnimationUtils.h>
 #import <React/RCTConversions.h>
+#import <TargetConditionals.h>
 #import <react/utils/FloatComparison.h>
 #include <optional>
 #import <vector>
 
+#if RCT_USE_KMP && TARGET_OS_IOS && !TARGET_OS_MACCATALYST
+#define RCT_GRADIENT_USE_KMP 1
+#import <ReactNativeShared/ReactNativeShared.h>
+#else
+#define RCT_GRADIENT_USE_KMP 0
+#endif
+
 using namespace facebook::react;
 
 namespace {
@@ -156,6 +164,45 @@ CGSize calculateMultipliers(CGSize bounds)
   return std::nullopt;
 }
 
+#if RCT_GRADIENT_USE_KMP
+static std::vector<ProcessedColorStop> resolveSharedColorStops(
+    const std::vector<ColorStop> &colorStops,
+    CGFloat gradientLineLength)
+{
+  NSMutableArray<RNSGradientStopInput *> *inputs = [NSMutableArray arrayWithCapacity:colorStops.size()];
+  for (const auto &stop : colorStops) {
+    auto position = resolveColorStopPosition(stop.position, gradientLineLength);
+    RNSDouble *boxedPosition = position.has_value() ? [RNSDouble numberWithDouble:position.value()] : nil;
+    auto input = [[RNSGradientStopInput alloc] initWithPosition:boxedPosition hasColor:static_cast<bool>(stop.color)];
+    [inputs addObject:input];
+  }
+
+  auto resolved = [RNSGradientStops.shared resolveStops:inputs epsilon:kDefaultEpsilon useDoublePrecision:YES];
+  std::vector<ProcessedColorStop> result;
+  result.reserve(resolved.count);
+  NSArray<NSNumber *> *inputRange = @[ @0.0, @1.0 ];
+  for (RNSResolvedGradientStop *stop in resolved) {
+    const auto &leftColor = colorStops[stop.leftColorIndex].color;
+    SharedColor color;
+    if (stop.leftColorIndex == stop.rightColorIndex) {
+      // Preserve the original native color, including dynamic UIColor behavior.
+      color = leftColor;
+    } else if (std::isfinite(stop.weight)) {
+      const auto &rightColor = colorStops[stop.rightColorIndex].color;
+      NSArray<UIColor *> *outputRange =
+          @[ RCTUIColorFromSharedColor(leftColor), RCTUIColorFromSharedColor(rightColor) ];
+      auto interpolatedColor = RCTInterpolateColorInRange(stop.weight, inputRange, outputRange);
+      auto alpha = (interpolatedColor >> 24) & 0xFF;
+      auto red = (interpolatedColor >> 16) & 0xFF;
+      auto green = (interpolatedColor >> 8) & 0xFF;
+      auto blue = interpolatedColor & 0xFF;
+      color = colorFromRGBA(red, green, blue, alpha);
+    }
+    result.push_back({.color = color, .position = stop.position});
+  }
+  return result;
+}
+#else
 // Spec: https://drafts.csswg.org/css-images-4/#coloring-gradient-line (Refer transition hint section)
 // Browsers add 9 intermediate color stops when a transition hint is present
 // Algorithm is referred from Blink engine
@@ -261,12 +308,16 @@ CGSize calculateMultipliers(CGSize bounds)
 
   return colorStops;
 }
+#endif
 
 @implementation RCTGradientUtils
 // https://drafts.csswg.org/css-images-4/#color-stop-fixup
 + (std::vector<ProcessedColorStop>)getFixedColorStops:(const std::vector<ColorStop> &)colorStops
                                    gradientLineLength:(CGFloat)gradientLineLength
 {
+#if RCT_GRADIENT_USE_KMP
+  return resolveSharedColorStops(colorStops, gradientLineLength);
+#else
   if (colorStops.empty()) {
     return {};
   }
@@ -334,6 +385,7 @@ @implementation RCTGradientUtils
     }
   }
   return processColorTransitionHints(fixedColorStops);
+#endif
 }
 
 // CAGradientLayer linear gradient squishes the non-square gradient to square gradient.

packages/react-native/React/React-RCTFabric.podspec

@@ -17,6 +17,10 @@ else
 end
 
 new_arch_flags = ENV['RCT_NEW_ARCH_ENABLED'] == '1' ? ' -DRCT_NEW_ARCH_ENABLED=1' : ''
+kmp_enabled = ENV['RCT_USE_KMP'] == '1'
+if kmp_enabled && ENV['RCT_USE_PREBUILT_RNCORE'] != '0'
+  raise 'RCT_USE_KMP=1 requires React Native core source builds. Use use_react_native! or set RCT_USE_PREBUILT_RNCORE=0.'
+end
 
 header_search_paths = [
   "\"$(PODS_TARGET_SRCROOT)/ReactCommon\"",
@@ -50,13 +54,26 @@ Pod::Spec.new do |s|
   s.module_name            = module_name
   s.weak_framework         = "JavaScriptCore"
   s.framework              = "MobileCoreServices"
-  s.pod_target_xcconfig    = {
+  pod_target_xcconfig = {
     "HEADER_SEARCH_PATHS" => header_search_paths,
     "OTHER_CFLAGS" => "$(inherited) " + new_arch_flags,
     "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard()
   }.merge!(ENV['USE_FRAMEWORKS'] != nil ? {
     "PUBLIC_HEADERS_FOLDER_PATH" => "#{module_name}.framework/Headers/#{header_dir}"
   }: {})
+  if kmp_enabled
+    # Catalyst has no Kotlin/Native target. Its build keeps the existing implementation.
+    s.dependency 'React-KMP'
+    pod_target_xcconfig.merge!({
+      'GCC_PREPROCESSOR_DEFINITIONS[sdk=iphoneos*]' => '$(inherited) RCT_USE_KMP=1',
+      'GCC_PREPROCESSOR_DEFINITIONS[sdk=iphonesimulator*]' => '$(inherited) RCT_USE_KMP=1',
+      'FRAMEWORK_SEARCH_PATHS[sdk=iphoneos*]' => '$(inherited) "$(PODS_CONFIGURATION_BUILD_DIR)/ReactNativeSharedKMP"',
+      'FRAMEWORK_SEARCH_PATHS[sdk=iphonesimulator*]' => '$(inherited) "$(PODS_CONFIGURATION_BUILD_DIR)/ReactNativeSharedKMP"',
+      'OTHER_LDFLAGS[sdk=iphoneos*]' => '$(inherited) -framework ReactNativeShared',
+      'OTHER_LDFLAGS[sdk=iphonesimulator*]' => '$(inherited) -framework ReactNativeShared',
+    })
+  end
+  s.pod_target_xcconfig = pod_target_xcconfig
 
   s.dependency "React-Core"
   s.dependency "React-RCTImage"

packages/react-native/ReactAndroid/build.gradle.kts

@@ -717,6 +717,12 @@ tasks.withType<KotlinCompile>().configureEach {
 }
 
 dependencies {
+  // Embed the common Kotlin implementation in react-android's AAR. This keeps published
+  // consumers on the existing artifact instead of requiring a separate KMP publication.
+  implementation(
+      files("$reactNativeRootDir/ReactShared/build/android/react-native-shared.jar")
+          .builtBy(gradle.includedBuild("react-native-shared").task(":exportAndroidJar"))
+  )
   api(libs.androidx.appcompat)
   api(libs.androidx.appcompat.resources)
   api(libs.androidx.autofill)