Fix skewX/skewY transforms on Android Q+ (#27649) (#56724)

Summary:
Fixes #27649.

On Android, `skewX` / `skewY` transforms are silently dropped during view-prop application: the matrix math layer correctly extracts the shear into `MatrixDecompositionContext.skew[]`, but `BaseViewManager.setTransformProperty` reads only `translation`, `rotationDegrees`, `scale`, and `perspective` from the decomposition context and never consumes the `skew[]` field. Views with `skew*` end up rendered as rotated-and-scaled rectangles instead of true parallelograms.

This PR adds a single dispatch in `BaseViewManager.setTransformProperty`: when the transform array contains `skewX` / `skewY` and is otherwise 2D-affine, build a `Matrix` directly from the operations and apply it via `View.setAnimationMatrix` on Android Q+. All other transform shapes (`rotateX`, `rotateY`, `perspective`, raw 4x4 `matrix`, `translateZ`) continue to flow through the existing decompose-and-set-View-props code unchanged.

### Root cause

`packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/BaseViewManager.java` (the pre-fix range `~573-635`) iterates the decomposed `translation`, `rotationDegrees`, `scale`, and `perspective` fields onto the View. The `skew[]` field on `MatrixDecompositionContext`, computed correctly by `MatrixMathHelper.decomposeMatrix`, is never read. Android `View` exposes property setters for translation, rotation around pivot, scale, and camera distance, but no `setSkewX` / `setSkewY`, so there has historically been no application path for the residual shear.

quantizor's trace in #27649 (comment) identified the exact site.

### Fix

A new internal Kotlin helper `SkewMatrixHelper` (in `packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/SkewMatrixHelper.kt`) exposes two `JvmStatic` functions:

- `isAffine2DTransformWithSkew(transforms)`, linear scan; returns true iff the array contains at least one `skewX` / `skewY` AND no operation that can't be represented by a 2D Skia `Matrix` (rejects `matrix`, `perspective`, `rotateX`, `rotateY`, `translate` with a non-zero Z component, and the raw 16-element matrix shorthand used by Fabric LayoutAnimations).
- `buildAffine2DMatrix(transforms, viewWidthDip, viewHeightDip, transformOrigin)`, walks the array left-to-right and applies each operation to a `Matrix` via `preRotate` / `preScale` / `preSkew` / `preTranslate` around the resolved pivot. Composition is pre-multiplication so the rightmost array entry is applied first to the point, matching CSS / iOS conventions and `MatrixMathHelper.multiplyInto` in `TransformHelper.processTransform`. Reuses `TransformHelper.convertToRadians` / `TransformHelper.parseTranslateValue` so degree/radian/percent parsing stays in one place.

`BaseViewManager.setTransformProperty` adds a guarded dispatch immediately after the `transforms == null` reset block:

```java
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q
    && SkewMatrixHelper.isAffine2DTransformWithSkew(transforms)) {
  Matrix affine =
      SkewMatrixHelper.buildAffine2DMatrix(
          transforms,
          PixelUtil.toDIPFromPixel(view.getWidth()),
          PixelUtil.toDIPFromPixel(view.getHeight()),
          transformOrigin);
  view.setTranslationX(0);
  view.setTranslationY(0);
  view.setRotation(0);
  view.setRotationX(0);
  view.setRotationY(0);
  view.setScaleX(1);
  view.setScaleY(1);
  view.setCameraDistance(0);
  view.setAnimationMatrix(affine);
  view.setTag(R.id.skew_animation_matrix, affine);
  return;
}
```

The `R.id.skew_animation_matrix` tag (declared in `ids.xml`) holds the affine `Matrix` itself. A small `clearSkewAnimationMatrixIfActive(view)` helper is invoked from the `transforms == null` branch and from the existing decompose-path tail, gating the `view.setAnimationMatrix(null)` call on the tag. Without this gate, every animated rotate / scale / translate frame on every View would fire `setAnimationMatrix(null)`, which unconditionally invalidates the RenderNode and would be a per-frame regression for non-skew animations.

`View.getMatrix()` does not compose `mAnimationMatrix` into its return value, so the React-side hit-test traversal in `TouchTargetHelper.kt` would otherwise still see the original rectangular bounds. To close that gap, the `R.id.skew_animation_matrix` view tag stores the affine `Matrix` itself (rather than `Boolean.TRUE`), and `TouchTargetHelper.getChildPoint` checks the tag and uses it as the inverse-mapping matrix when present. Net effect: hit testing follows the rendered parallelogram on both platforms, matching iOS / `CATransform3D` behavior. Invalidation, layer caching, and accessibility-bounds reporting come for free from the existing `setAnimationMatrix` plumbing.

### Pre-Q

Gated to API 29+ to mirror the existing `view.setAnimationMatrix(null)` cleanup at `BaseViewManager.java:118`. On API 24-28 (small and declining install share in 2026), skew continues to be silently dropped, matching today's behavior. AndroidX Transitions uses `setAnimationMatrix` via reflection on pre-Q; if that ever becomes a priority for skew on pre-Q, the same shim could be added here without touching the dispatch shape.

### Why not the prior attempts

- **#28862 (`wcandillon`, May 2020), fixed a JS-side decomposition bug where `skew[0]` was zeroed by a duplicate orthogonalization. That fix landed via Phabricator (commit `797367c0890a38ec51cfaf7bd90b9cc7db0e97c7`) and is preserved in current `main`. It corrected `decomposeMatrix` but did not address the application layer; this PR is the missing application path.

- **#38494 (`xxrlzzz`, Jul 2023, closed Apr 2024), closest in spirit to this fix. It built a Skia `Matrix` and applied via `setAnimationMatrix` for a broader class of 2D transforms, plus a reflection shim for pre-Q. javache's review raised two concerns: (1) the SDK doc framing of `setAnimationMatrix` as an animation API, and (2) "two divergent code paths" complexity. This PR addresses both: (1) AndroidX `androidx.transition.ViewUtilsApi21` invokes the same API for static transforms in production today, and the API was promoted to public in API 29; the precedent is established. (2) The dispatch is tightened to `isAffine2DTransformWithSkew`, so the new path runs only for transforms that are broken under the existing path; the rotate / scale / translate / rotateX / rotateY / perspective code stays bit-identical. The reflection shim is intentionally not adopted; pre-Q skew remains dropped.

- **#42676 (`piaskowyk` + `bartlomiejbloniarz`, Jan 2024, closed Aug 2025), simulated skew via 3D rotation + non-uniform scale + perspective hack. The 2x2 sub-matrix matches a true skew, but the 4x4 differs in the third row/column, so composition with real `rotateX` / `rotateY` produces wrong results. The PR author acknowledged this in the description. Not the right shape.

## Changelog:

[ANDROID] [FIXED] - skewX / skewY transforms now render correctly on Android Q+.

Pull Request resolved: #56724

Test Plan:
### Unit tests

- `./gradlew :packages:react-native:ReactAndroid:testDebugUnitTest --tests 'com.facebook.react.uimanager.SkewMatrixHelperTest*'`, 17 / 17 pass (predicate cases for `hasSkewTransform` and `isAffine2DTransform`; matrix-math cases for `buildAffine2DMatrix` covering pure skewX, scale-then-translate ordering, view-center pivot default, and `transformOrigin` overrides via Number values and "%" strings).
- `yarn jest packages/react-native/Libraries/StyleSheet/__tests__/processTransform-test.js`, 16 / 16 + 19 / 19 snapshots, unchanged.
- `./gradlew ktfmtCheck`, `yarn lint`, `yarn flow`, all clean.

### Manual verification (Android, rn_test AVD: Pixel 8 Pro, Android 16, arm64-v8a)

RNTester -> APIs -> Transforms -> "Skew (#27649)" (the new permanent example added in this PR).

| Before | After |
| --- | --- |
| <img src="https://raw.githubusercontent.com/qflen/react-native/f4585e841aba90b69c11474dbfdc3e9540b8f0ee/assets/27649/before_android_skew_scene.png" width="260"> | <img src="https://raw.githubusercontent.com/qflen/react-native/f4585e841aba90b69c11474dbfdc3e9540b8f0ee/assets/27649/after_android_skew_scene.png" width="260"> |
| Boxes render as rotated rectangles. Decompose extracts ~20 deg of rotation plus non-uniform scale; the residual shear is dropped. | Boxes render as true parallelograms. Top and bottom edges horizontal, sides tilted by 20 deg. |

Hit testing follows the rendered parallelogram. Without commit 2, the rendering fix would land alone: parallelograms render but `TouchTargetHelper.getChildPoint` would still inverse-map through `child.matrix` (which doesn't compose `mAnimationMatrix`) and clip to the original rectangle. Verified empirically by sweeping tap coordinates 1 px on either side of every parallelogram edge on the skewX box (rect bounds `[116, 549] [300, 732]` on the rn_test AVD):

- `(100, 555)`: inside parallelogram top-left tip, outside the rect. With only commit 1: misses. With commit 2 added: registers as `skewX 20deg`.
- `(330, 731)`: bottom-right tip. Same flip.
- `(208, 640)`: parallelogram / rect center. Registers either way.
- `(350, 640)`: outside the parallelogram at vertical-pivot y. Misses either way (correct).

The new `Skew (https://github.com/facebook/react-native/issues/27649)` example also includes a `useNativeDriver: true` `Animated.timing` interpolating skewX from `0deg` to `20deg`. Native-driven animations re-emit the transform array per frame via `TransformAnimatedNode.collectViewUpdates -> setTransformProperty`, so the dispatch runs each frame and the skew animates smoothly.

### iOS

iOS already handles skewX / skewY correctly via `CATransform3D` (Paper: `RCTConvert+Transform.m` sets `next.m21 = tanf(skew)` for skewX and `next.m12 = tanf(skew)` for skewY; Fabric: `RCTViewComponentView.mm` calls `resolveTransform` -> `RCTCATransform3DFromTransformMatrix` -> `layer.transform`). This PR does not touch that path; the AFTER Android rendering above matches the existing iOS rendering.

### Negative case

Existing transform examples (Translate-Rotate-Scale, Perspective-Rotate-Animation, Rotate-Scale, Transform-using-a-string, Transform-Matrix-2D / 3D) render bit-identically to `origin/main`. The `hasSkewTransform` predicate filters them out of the new path, so they go through the unchanged decompose-and-set-View-props code. The new `setAnimationMatrix(null)` clearing call on the fallthrough path is gated by the `R.id.skew_animation_matrix` view tag, so it fires only on the skew -> non-skew transition; non-skew animations have no per-frame regression.

Reviewed By: christophpurrer

Differential Revision: D106497417

Pulled By: javache

fbshipit-source-id: 68f378a34c389a92fc7f161a31c7134cf6d8ee36

Author: qflen

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/BaseViewManager.java

@@ -8,6 +8,7 @@
 package com.facebook.react.uimanager;
 
 import android.graphics.Color;
+import android.graphics.Matrix;
 import android.graphics.Paint;
 import android.os.Build;
 import android.text.TextUtils;
@@ -579,6 +580,31 @@ protected void setTransformProperty(
       view.setScaleX(1);
       view.setScaleY(1);
       view.setCameraDistance(0);
+      clearSkewAnimationMatrixIfActive(view);
+      return;
+    }
+
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q
+        && SkewMatrixHelper.isAffine2DTransformWithSkew(transforms)) {
+      Matrix affine =
+          SkewMatrixHelper.buildAffine2DMatrix(
+              transforms,
+              PixelUtil.toDIPFromPixel(view.getWidth()),
+              PixelUtil.toDIPFromPixel(view.getHeight()),
+              transformOrigin);
+      view.setTranslationX(0);
+      view.setTranslationY(0);
+      view.setRotation(0);
+      view.setRotationX(0);
+      view.setRotationY(0);
+      view.setScaleX(1);
+      view.setScaleY(1);
+      view.setCameraDistance(0);
+      view.setAnimationMatrix(affine);
+      // Tag value is the matrix itself so TouchTargetHelper can use it for hit testing -- View's
+      // own getMatrix() does not compose mAnimationMatrix, so without this fallback the React
+      // hit-test path would still see the original rectangular bounds.
+      view.setTag(R.id.skew_animation_matrix, affine);
       return;
     }
 
@@ -628,6 +654,21 @@ protected void setTransformProperty(
               scale * scale * cameraDistance * CAMERA_DISTANCE_NORMALIZATION_MULTIPLIER);
       view.setCameraDistance(normalizedCameraDistance);
     }
+
+    clearSkewAnimationMatrixIfActive(view);
+  }
+
+  // setAnimationMatrix is called only on the transition out of a skew matrix; calling it
+  // unconditionally would invalidate the View's RenderNode every frame for any non-skew animation.
+  private static <T extends View> void clearSkewAnimationMatrixIfActive(@NonNull T view) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) {
+      return;
+    }
+    if (view.getTag(R.id.skew_animation_matrix) == null) {
+      return;
+    }
+    view.setAnimationMatrix(null);
+    view.setTag(R.id.skew_animation_matrix, null);
   }
 
   /**

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/SkewMatrixHelper.kt

@@ -0,0 +1,196 @@
+/*
+ * 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.
+ */
+
+package com.facebook.react.uimanager
+
+import android.graphics.Matrix
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
+
+/**
+ * Builds a 2D-affine [Matrix] from a `transform` array for the subset of operations Android `View`
+ * cannot represent through its individual property setters (specifically `skewX` / `skewY`). Used
+ * by [BaseViewManager.setTransformProperty] to apply such transforms via `View.setAnimationMatrix`
+ * on Android Q+.
+ */
+internal object SkewMatrixHelper {
+  /**
+   * Returns true if [transforms] contains only operations representable by a Skia [Matrix] in 2D:
+   * `rotate` / `rotateZ`, `scale`, `scaleX` / `scaleY`, `translate` / `translateX` / `translateY`
+   * with zero Z, `skewX`, `skewY`. Returns false for `matrix`, `perspective`, `rotateX`, `rotateY`,
+   * a `translate` with a non-zero Z component, and the raw 16-element matrix shorthand used by
+   * Fabric LayoutAnimations.
+   */
+  @JvmStatic
+  fun isAffine2DTransformWithSkew(transforms: ReadableArray): Boolean {
+    if (isRawMatrixShorthand(transforms)) {
+      return false
+    }
+
+    var hasSkewTransform = false
+    for (i in 0 until transforms.size()) {
+      if (transforms.getType(i) != ReadableType.Map) continue
+      val map = transforms.getMap(i) ?: continue
+      val type = map.keySetIterator().nextKey()
+      when (type) {
+        "matrix",
+        "perspective",
+        "rotateX",
+        "rotateY" -> return false
+        "translate" -> {
+          val value = map.getArray(type)
+          if (
+              value != null &&
+                  value.size() > 2 &&
+                  value.getType(2) == ReadableType.Number &&
+                  value.getDouble(2) != 0.0
+          ) {
+            return false
+          }
+        }
+        "skewX",
+        "skewY" -> hasSkewTransform = true
+      }
+    }
+    return hasSkewTransform
+  }
+
+  /**
+   * Builds a [Matrix] in pixel coordinates by walking [transforms] left-to-right and applying each
+   * operation via `Matrix.preX` around the resolved pivot. Pivot is the view center; if
+   * [transformOrigin] is set, it overrides per-axis (Number values are DIP, "P%" strings are P/100
+   * of the view dimension; Z is ignored).
+   *
+   * Composition is pre-multiplication: when the resulting matrix is applied to a point, the
+   * rightmost (last) array entry is applied first. Matches CSS / iOS conventions and the
+   * left-to-right-iteration / right-multiply contract of [MatrixMathHelper.multiplyInto] used by
+   * [TransformHelper.processTransform].
+   */
+  @JvmStatic
+  fun buildAffine2DMatrix(
+      transforms: ReadableArray,
+      viewWidthDip: Float,
+      viewHeightDip: Float,
+      transformOrigin: ReadableArray?,
+  ): Matrix {
+    val pivotXPx: Float
+    val pivotYPx: Float
+    if (transformOrigin == null) {
+      pivotXPx = PixelUtil.toPixelFromDIP(viewWidthDip / 2f)
+      pivotYPx = PixelUtil.toPixelFromDIP(viewHeightDip / 2f)
+    } else {
+      pivotXPx =
+          PixelUtil.toPixelFromDIP(
+              resolveOriginAxis(transformOrigin, 0, viewWidthDip, viewWidthDip / 2f)
+          )
+      pivotYPx =
+          PixelUtil.toPixelFromDIP(
+              resolveOriginAxis(transformOrigin, 1, viewHeightDip, viewHeightDip / 2f)
+          )
+    }
+
+    val matrix = Matrix()
+    for (i in 0 until transforms.size()) {
+      if (transforms.getType(i) != ReadableType.Map) continue
+      val map = transforms.getMap(i) ?: continue
+      val type = map.keySetIterator().nextKey()
+      when (type) {
+        "rotate",
+        "rotateZ" ->
+            matrix.preRotate(
+                Math.toDegrees(TransformHelper.convertToRadians(map, type)).toFloat(),
+                pivotXPx,
+                pivotYPx,
+            )
+        "scale" -> {
+          val s = map.getDouble(type).toFloat()
+          matrix.preScale(s, s, pivotXPx, pivotYPx)
+        }
+        "scaleX" -> matrix.preScale(map.getDouble(type).toFloat(), 1f, pivotXPx, pivotYPx)
+        "scaleY" -> matrix.preScale(1f, map.getDouble(type).toFloat(), pivotXPx, pivotYPx)
+        "skewX" ->
+            matrix.preSkew(
+                Math.tan(TransformHelper.convertToRadians(map, type)).toFloat(),
+                0f,
+                pivotXPx,
+                pivotYPx,
+            )
+        "skewY" ->
+            matrix.preSkew(
+                0f,
+                Math.tan(TransformHelper.convertToRadians(map, type)).toFloat(),
+                pivotXPx,
+                pivotYPx,
+            )
+        "translate" -> {
+          val value = map.getArray(type)
+          if (value != null && value.size() >= 1) {
+            val tx = parseTranslateValue(value, 0, viewWidthDip)
+            val ty = if (value.size() > 1) parseTranslateValue(value, 1, viewHeightDip) else 0.0
+            matrix.preTranslate(
+                PixelUtil.toPixelFromDIP(tx.toFloat()),
+                PixelUtil.toPixelFromDIP(ty.toFloat()),
+            )
+          }
+        }
+        "translateX" ->
+            matrix.preTranslate(
+                PixelUtil.toPixelFromDIP(parseScalarTranslate(map, type, viewWidthDip).toFloat()),
+                0f,
+            )
+        "translateY" ->
+            matrix.preTranslate(
+                0f,
+                PixelUtil.toPixelFromDIP(parseScalarTranslate(map, type, viewHeightDip).toFloat()),
+            )
+      }
+    }
+    return matrix
+  }
+
+  private fun isRawMatrixShorthand(transforms: ReadableArray): Boolean =
+      transforms.size() == 16 && transforms.getType(0) == ReadableType.Number
+
+  private fun resolveOriginAxis(
+      origin: ReadableArray,
+      axis: Int,
+      dimensionDip: Float,
+      defaultDip: Float,
+  ): Float {
+    if (origin.size() <= axis) return defaultDip
+    return when (origin.getType(axis)) {
+      ReadableType.Number -> origin.getDouble(axis).toFloat()
+      ReadableType.String -> {
+        val part = origin.getString(axis) ?: return defaultDip
+        if (!part.endsWith("%")) return defaultDip
+        try {
+          (part.dropLast(1).toDouble() * dimensionDip / 100.0).toFloat()
+        } catch (e: NumberFormatException) {
+          defaultDip
+        }
+      }
+      else -> defaultDip
+    }
+  }
+
+  private fun parseTranslateValue(value: ReadableArray, index: Int, dimensionDip: Float): Double {
+    if (value.getType(index) != ReadableType.String) {
+      return value.getDouble(index)
+    }
+    val s = value.getString(index) ?: return 0.0
+    return TransformHelper.parseTranslateValue(s, dimensionDip.toDouble())
+  }
+
+  private fun parseScalarTranslate(map: ReadableMap, key: String, dimensionDip: Float): Double {
+    if (map.getType(key) != ReadableType.String) {
+      return map.getDouble(key)
+    }
+    val s = map.getString(key) ?: return 0.0
+    return TransformHelper.parseTranslateValue(s, dimensionDip.toDouble())
+  }
+}

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/TouchTargetHelper.kt

@@ -13,6 +13,7 @@ import android.graphics.PointF
 import android.view.View
 import android.view.ViewGroup
 import com.facebook.common.logging.FLog
+import com.facebook.react.R
 import com.facebook.react.bridge.UiThreadUtil
 import com.facebook.react.common.ReactConstants
 import com.facebook.react.touch.ReactHitSlopView
@@ -298,7 +299,11 @@ public object TouchTargetHelper {
   ): Boolean {
     var localX = x + parent.scrollX - child.left
     var localY = y + parent.scrollY - child.top
-    val matrix = child.matrix
+    // BaseViewManager applies skewX / skewY through View.setAnimationMatrix, which is composed
+    // for drawing but not exposed via View.getMatrix(); fall back to the stashed matrix so hit
+    // testing follows the rendered parallelogram and not the original rectangle.
+    val skewMatrix = child.getTag(R.id.skew_animation_matrix) as? Matrix
+    val matrix = skewMatrix ?: child.matrix
     if (!matrix.isIdentity) {
       val inverseMatrix = inverseMatrix
       if (!matrix.invert(inverseMatrix)) {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/TransformHelper.kt

@@ -25,7 +25,7 @@ public object TransformHelper {
         override fun initialValue(): DoubleArray = DoubleArray(16)
       }
 
-  private fun convertToRadians(transformMap: ReadableMap, key: String): Double {
+  internal fun convertToRadians(transformMap: ReadableMap, key: String): Double {
     var value: Double
     var inRadians = true
     if (transformMap.getType(key) == ReadableType.String) {
@@ -189,7 +189,7 @@ public object TransformHelper {
     }
   }
 
-  private fun parseTranslateValue(stringValue: String, dimension: Double): Double {
+  internal fun parseTranslateValue(stringValue: String, dimension: Double): Double {
     return try {
       if (stringValue.endsWith("%")) {
         val percentage = stringValue.dropLast(1).toDouble()

packages/react-native/ReactAndroid/src/main/res/views/uimanager/values/ids.xml

@@ -66,6 +66,11 @@
   <!-- tag is used to invalidate transform style in view manager -->
   <item type="id" name="invalidate_transform"/>
 
+  <!-- tag stores the active 2D-affine skew Matrix applied to the View via setAnimationMatrix,
+       so non-skew updates can clear it only on the transition out and TouchTargetHelper can
+       reuse it for hit testing -->
+  <item type="id" name="skew_animation_matrix"/>
+
   <!-- tag is used to store if we should render the view to a hardware texture -->
   <item type="id" name="use_hardware_layer"/>