Add ImportantForInteractionHelper for interaction handling (#55168)

Summary:
Pull Request resolved: #55168

Changelog: [Internal]

This diff introduces `ImportantForInteractionHelper`, a helper class that manages the `important_for_interaction` view tag. This tag determines how a view participates in interaction handling based on its `pointerEvents` value.

The helper provides a mapping from `PointerEvents` to `important_for_interaction` values:
- `AUTO` → `YES` (0x1)
- `NONE` → `NO | EXCLUDE_DESCENDANTS` (0x2 | 0x8)
- `BOX_ONLY` → `YES | EXCLUDE_DESCENDANTS` (0x1 | 0x8)
- `BOX_NONE` → `NO` (0x2)

This allows interaction detection systems to understand which views should participate in interaction handling based on their pointer events configuration, which is useful for features like Gaze-based interaction in accessibility and UI harvesting.

See design doc: https://docs.google.com/document/d/15Fi47zOHQh--KFWLUxQAUmBENgnZ0ZkYsKyOshPzBAo/edit?tab=t.0#heading=h.61xuoxksjdrp

Changes:
- Added `ImportantForInteractionHelper.kt` with constants and `setImportantForInteraction()` method
- Added `important_for_interaction` tag ID to `ids.xml`
- Updated `ReactViewManager.setPointerEvents()` to set the tag when pointer events change
- Updated `ReactViewGroup.initView()` to set the default tag value based on initial `PointerEvents.AUTO`
- Updated `BaseViewManager.prepareToRecycleView()` to clear the tag when recycling views

Reviewed By: javache, mdvacca

Differential Revision: D90386675

fbshipit-source-id: f0dab0111f2f5d14d5cb17769578804e2ddcbfe9

Author: fabriziocucci

packages/react-native/ReactAndroid/api/ReactAndroid.api

@@ -3359,6 +3359,14 @@ public class com/facebook/react/uimanager/IllegalViewOperationException : com/fa
 	public final fun getView ()Landroid/view/View;
 }
 
+public final class com/facebook/react/uimanager/ImportantForInteractionHelper {
+	public static final field IMPORTANT_FOR_INTERACTION_EXCLUDE_DESCENDANTS I
+	public static final field IMPORTANT_FOR_INTERACTION_NO I
+	public static final field IMPORTANT_FOR_INTERACTION_YES I
+	public static final field INSTANCE Lcom/facebook/react/uimanager/ImportantForInteractionHelper;
+	public static final fun setImportantForInteraction (Landroid/view/View;Lcom/facebook/react/uimanager/PointerEvents;)V
+}
+
 public class com/facebook/react/uimanager/JSPointerDispatcher {
 	public fun <init> (Landroid/view/ViewGroup;)V
 	public fun handleMotionEvent (Landroid/view/MotionEvent;Lcom/facebook/react/uimanager/events/EventDispatcher;Z)V

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

@@ -79,6 +79,7 @@ public BaseViewManager(@Nullable ReactApplicationContext reactContext) {
     // Reset tags
     view.setTag(null);
     view.setTag(R.id.pointer_events, null);
+    view.setTag(R.id.important_for_interaction, null);
     view.setTag(R.id.react_test_id, null);
     view.setTag(R.id.view_tag_native_id, null);
     view.setTag(R.id.labelled_by, null);

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

@@ -0,0 +1,60 @@
+/*
+ * 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.view.View
+import com.facebook.react.R
+
+/**
+ * Helper class for managing the important_for_interaction view tag. This tag determines how a view
+ * participates in interaction handling.
+ *
+ * The important_for_interaction value is a bitfield that can contain combinations of:
+ * - [IMPORTANT_FOR_INTERACTION_YES]: The view is important for interaction
+ * - [IMPORTANT_FOR_INTERACTION_NO]: The view is not important for interaction
+ * - [IMPORTANT_FOR_INTERACTION_EXCLUDE_DESCENDANTS]: Descendants should be excluded from
+ *   interaction
+ */
+public object ImportantForInteractionHelper {
+  /** The view is important for interaction. */
+  public const val IMPORTANT_FOR_INTERACTION_YES: Int = 0x1
+
+  /** The view is not important for interaction. */
+  public const val IMPORTANT_FOR_INTERACTION_NO: Int = 0x2
+
+  /** Descendants of this view should be excluded from interaction handling. */
+  public const val IMPORTANT_FOR_INTERACTION_EXCLUDE_DESCENDANTS: Int = 0x8
+
+  /**
+   * Sets the important_for_interaction tag on a view based on the given [PointerEvents] value.
+   *
+   * The mapping is as follows:
+   * - [PointerEvents.AUTO] -> [IMPORTANT_FOR_INTERACTION_YES]
+   * - [PointerEvents.NONE] -> [IMPORTANT_FOR_INTERACTION_NO] |
+   *   [IMPORTANT_FOR_INTERACTION_EXCLUDE_DESCENDANTS]
+   * - [PointerEvents.BOX_ONLY] -> [IMPORTANT_FOR_INTERACTION_YES] |
+   *   [IMPORTANT_FOR_INTERACTION_EXCLUDE_DESCENDANTS]
+   * - [PointerEvents.BOX_NONE] -> [IMPORTANT_FOR_INTERACTION_NO]
+   *
+   * @param view The view to set the tag on
+   * @param pointerEvents The pointer events value to convert and set
+   */
+  @JvmStatic
+  public fun setImportantForInteraction(view: View, pointerEvents: PointerEvents) {
+    val value =
+        when (pointerEvents) {
+          PointerEvents.AUTO -> IMPORTANT_FOR_INTERACTION_YES
+          PointerEvents.NONE ->
+              IMPORTANT_FOR_INTERACTION_NO or IMPORTANT_FOR_INTERACTION_EXCLUDE_DESCENDANTS
+          PointerEvents.BOX_ONLY ->
+              IMPORTANT_FOR_INTERACTION_YES or IMPORTANT_FOR_INTERACTION_EXCLUDE_DESCENDANTS
+          PointerEvents.BOX_NONE -> IMPORTANT_FOR_INTERACTION_NO
+        }
+    view.setTag(R.id.important_for_interaction, value)
+  }
+}

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/view/ReactViewGroup.kt

@@ -44,6 +44,7 @@ import com.facebook.react.uimanager.BackgroundStyleApplicator.setBorderStyle
 import com.facebook.react.uimanager.BackgroundStyleApplicator.setBorderWidth
 import com.facebook.react.uimanager.BackgroundStyleApplicator.setFeedbackUnderlay
 import com.facebook.react.uimanager.BlendModeHelper.needsIsolatedLayer
+import com.facebook.react.uimanager.ImportantForInteractionHelper
 import com.facebook.react.uimanager.LengthPercentage
 import com.facebook.react.uimanager.LengthPercentageType
 import com.facebook.react.uimanager.MeasureSpecAssertions.assertExplicitMeasureSpec
@@ -176,6 +177,7 @@ public open class ReactViewGroup public constructor(context: Context?) :
     hitSlopRect = null
     _overflow = Overflow.VISIBLE
     pointerEvents = PointerEvents.AUTO
+    ImportantForInteractionHelper.setImportantForInteraction(this, pointerEvents)
     childrenLayoutChangeListener = null
     onInterceptTouchEventListener = null
     needsOffscreenAlphaCompositing = false

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/view/ReactViewManager.kt

@@ -21,6 +21,7 @@ import com.facebook.react.common.ReactConstants
 import com.facebook.react.internal.featureflags.ReactNativeFeatureFlags
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.uimanager.BackgroundStyleApplicator
+import com.facebook.react.uimanager.ImportantForInteractionHelper
 import com.facebook.react.uimanager.LengthPercentage
 import com.facebook.react.uimanager.LengthPercentageType
 import com.facebook.react.uimanager.PixelUtil.dpToPx
@@ -321,6 +322,7 @@ public open class ReactViewManager : ReactClippingViewManager<ReactViewGroup>()
   @ReactProp(name = ViewProps.POINTER_EVENTS)
   public open fun setPointerEvents(view: ReactViewGroup, pointerEventsStr: String?) {
     view.pointerEvents = PointerEvents.parsePointerEvents(pointerEventsStr)
+    ImportantForInteractionHelper.setImportantForInteraction(view, view.pointerEvents)
   }
 
   @ReactProp(name = "nativeBackgroundAndroid")

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

@@ -74,4 +74,7 @@
 
   <!-- tag is used to store mixBlendMode effects to apply to the view -->
   <item type="id" name="mix_blend_mode"/>
+
+  <!-- tag is used to store important_for_interaction state -->
+  <item type="id" name="important_for_interaction"/>
 </resources>