Add text fragment rect measurement APIs (facebook#55279)

Summary:

Adds Android-specific implementation for measuring bounding rectangles of
text fragments that belong to a specific React tag. This enables getting
the visual boundaries of nested `<Text>` components within a paragraph.

The implementation provides two methods:
1. `getFragmentRectsForReactTag` - Uses PreparedLayout for efficient measurement
   when the enablePreparedTextLayout feature flag is enabled
2. `getFragmentRectsFromAttributedString` - Fallback that creates a layout
   on-demand when PreparedLayout is not available

Key features:
- Handles multi-line text fragments by returning a rect for each line
- Correctly handles RTL text direction
- Converts coordinates between pixels and DIPs

These methods are used by the DOM getClientRects() API to provide accurate
text fragment boundaries for accessibility and layout inspection.

Differential Revision: D91087221

Author: andrewdacenko

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/FabricUIManager.java

@@ -705,6 +705,60 @@ public float[] measurePreparedLayout(
         getYogaMeasureMode(minHeight, maxHeight));
   }
 
+  /**
+   * Returns the bounding rectangles for all text fragments that belong to the specified react tag.
+   * This is useful for getting the visual boundaries of nested {@code <Text>} components within a
+   * paragraph.
+   *
+   * @param preparedLayout The prepared text layout containing the layout and react tags
+   * @param targetReactTag The react tag of the TextShadowNode to get rects for
+   * @return A FloatArray containing [x, y, width, height] for each fragment rect, or empty array if
+   *     no fragments match the tag
+   */
+  @AnyThread
+  @ThreadConfined(ANY)
+  @UnstableReactNativeAPI
+  public float[] getFragmentRectsForReactTag(PreparedLayout preparedLayout, int targetReactTag) {
+    return TextLayoutManager.getFragmentRectsForReactTag(preparedLayout, targetReactTag);
+  }
+
+  /**
+   * Returns the bounding rectangles for all text fragments that belong to the specified react tag
+   * by creating a layout on-demand from the AttributedString. This is used as a fallback when
+   * PreparedLayout is not available (e.g., when enablePreparedTextLayout feature flag is disabled).
+   *
+   * @param surfaceId The surface ID to get context from
+   * @param attributedString The attributed string containing the text fragments
+   * @param paragraphAttributes The paragraph attributes for layout
+   * @param width The layout width constraint
+   * @param height The layout height constraint
+   * @param targetReactTag The react tag of the TextShadowNode to get rects for
+   * @return A FloatArray containing [x, y, width, height] for each fragment rect, or empty array if
+   *     no fragments match the tag
+   */
+  @AnyThread
+  @ThreadConfined(ANY)
+  @UnstableReactNativeAPI
+  public float[] getFragmentRectsFromAttributedString(
+      int surfaceId,
+      ReadableMapBuffer attributedString,
+      ReadableMapBuffer paragraphAttributes,
+      float width,
+      float height,
+      int targetReactTag) {
+    SurfaceMountingManager surfaceMountingManager = mMountingManager.getSurfaceManager(surfaceId);
+    Context context = surfaceMountingManager != null ? surfaceMountingManager.getContext() : null;
+    if (context == null) {
+      FLog.w(
+          TAG,
+          "Couldn't get context for surfaceId %d in getFragmentRectsFromAttributedString",
+          surfaceId);
+      return new float[0];
+    }
+    return TextLayoutManager.getFragmentRectsFromAttributedString(
+        context, attributedString, paragraphAttributes, width, height, targetReactTag);
+  }
+
   /**
    * @param surfaceId {@link int} surface ID
    * @param defaultTextInputPadding {@link float[]} output parameter will contain the default theme

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/text/TextLayoutManager.kt

@@ -1195,6 +1195,234 @@ internal object TextLayoutManager {
     return ret
   }
 
+  /**
+   * Returns the bounding rectangles for all text fragments that belong to the specified react tag.
+   * This is useful for getting the visual boundaries of nested <Text> components within a
+   * paragraph.
+   *
+   * @param preparedLayout The prepared text layout containing the layout and react tags
+   * @param targetReactTag The react tag of the TextShadowNode to get rects for
+   * @return A FloatArray containing [x, y, width, height] for each fragment rect, or empty array if
+   *   no fragments match the tag
+   */
+  @JvmStatic
+  fun getFragmentRectsForReactTag(
+      preparedLayout: PreparedLayout,
+      targetReactTag: Int,
+  ): FloatArray {
+    val layout = preparedLayout.layout
+    val text = layout.text as? Spanned ?: return floatArrayOf()
+    val reactTags = preparedLayout.reactTags
+    val verticalOffset = preparedLayout.verticalOffset
+    val maximumNumberOfLines = preparedLayout.maximumNumberOfLines
+
+    val calculatedLineCount = calculateLineCount(layout, maximumNumberOfLines)
+    val retList = ArrayList<Float>()
+
+    // Find all fragments with the matching react tag
+    val fragmentIndexSpans = text.getSpans(0, text.length, ReactFragmentIndexSpan::class.java)
+
+    for (span in fragmentIndexSpans) {
+      val fragmentIndex = span.fragmentIndex
+      if (
+          fragmentIndex >= 0 &&
+              fragmentIndex < reactTags.size &&
+              reactTags[fragmentIndex] == targetReactTag
+      ) {
+        // This fragment belongs to the target TextShadowNode
+        val start = text.getSpanStart(span)
+        val end = text.getSpanEnd(span)
+
+        addRectsForSpanRange(layout, text, start, end, verticalOffset, calculatedLineCount, retList)
+      }
+    }
+
+    val ret = FloatArray(retList.size)
+    for (i in retList.indices) {
+      ret[i] = retList[i]
+    }
+    return ret
+  }
+
+  /**
+   * Returns the bounding rectangles for all text fragments that belong to the specified react tag.
+   * This method works with the legacy ReactTagSpan used when enablePreparedTextLayout is disabled.
+   *
+   * @param layout The Android text layout
+   * @param targetReactTag The react tag of the TextShadowNode to get rects for
+   * @param verticalOffset Vertical offset to apply to the rects
+   * @param maximumNumberOfLines Maximum number of lines to consider
+   * @return A FloatArray containing [x, y, width, height] for each fragment rect, or empty array if
+   *   no fragments match the tag
+   */
+  @JvmStatic
+  fun getFragmentRectsForReactTagFromLayout(
+      layout: Layout,
+      targetReactTag: Int,
+      verticalOffset: Float,
+      maximumNumberOfLines: Int,
+  ): FloatArray {
+    val text = layout.text as? Spanned ?: return floatArrayOf()
+    val calculatedLineCount = calculateLineCount(layout, maximumNumberOfLines)
+    val retList = ArrayList<Float>()
+
+    // Find all ReactTagSpan spans with the matching react tag
+    val tagSpans = text.getSpans(0, text.length, ReactTagSpan::class.java)
+
+    for (span in tagSpans) {
+      if (span.reactTag == targetReactTag) {
+        val start = text.getSpanStart(span)
+        val end = text.getSpanEnd(span)
+
+        addRectsForSpanRange(layout, text, start, end, verticalOffset, calculatedLineCount, retList)
+      }
+    }
+
+    val ret = FloatArray(retList.size)
+    for (i in retList.indices) {
+      ret[i] = retList[i]
+    }
+    return ret
+  }
+
+  /**
+   * Returns the bounding rectangles for all text fragments that belong to the specified react tag
+   * by creating a layout on-demand from the AttributedString. This is used as a fallback when
+   * PreparedLayout is not available (e.g., when enablePreparedTextLayout feature flag is disabled).
+   *
+   * @param context The Android context
+   * @param attributedString The attributed string containing the text fragments
+   * @param paragraphAttributes The paragraph attributes for layout
+   * @param width The layout width constraint
+   * @param height The layout height constraint
+   * @param targetReactTag The react tag of the TextShadowNode to get rects for
+   * @return A FloatArray containing [x, y, width, height] for each fragment rect, or empty array if
+   *   no fragments match the tag
+   */
+  @JvmStatic
+  fun getFragmentRectsFromAttributedString(
+      context: Context,
+      attributedString: ReadableMapBuffer,
+      paragraphAttributes: ReadableMapBuffer,
+      width: Float,
+      height: Float,
+      targetReactTag: Int,
+  ): FloatArray {
+    val fragments = attributedString.getMapBuffer(AS_KEY_FRAGMENTS)
+    // Pass null for outputReactTags since we'll use ReactTagSpan directly
+    val text =
+        createSpannableFromAttributedString(
+            context,
+            fragments,
+            null, // reactTextViewManagerCallback
+            null, // outputReactTags - this ensures ReactTagSpan is used
+        )
+
+    val baseTextAttributes =
+        TextAttributeProps.fromMapBuffer(attributedString.getMapBuffer(AS_KEY_BASE_ATTRIBUTES))
+
+    // Width and height from C++ are in DIPs, but createLayout expects pixels
+    // Convert to pixels for correct text wrapping
+    val widthInPx = width.dpToPx()
+    val heightInPx = height.dpToPx()
+
+    val layout =
+        createLayout(
+            text,
+            newPaintWithAttributes(baseTextAttributes, context),
+            attributedString,
+            paragraphAttributes,
+            widthInPx,
+            YogaMeasureMode.EXACTLY,
+            heightInPx,
+            YogaMeasureMode.UNDEFINED,
+        )
+
+    val maximumNumberOfLines =
+        if (paragraphAttributes.contains(PA_KEY_MAX_NUMBER_OF_LINES))
+            paragraphAttributes.getInt(PA_KEY_MAX_NUMBER_OF_LINES)
+        else ReactConstants.UNSET
+
+    val verticalOffset =
+        getVerticalOffset(
+            layout,
+            paragraphAttributes,
+            heightInPx,
+            YogaMeasureMode.UNDEFINED,
+            maximumNumberOfLines,
+        )
+
+    return getFragmentRectsForReactTagFromLayout(
+        layout,
+        targetReactTag,
+        verticalOffset,
+        maximumNumberOfLines,
+    )
+  }
+
+  private fun addRectsForSpanRange(
+      layout: Layout,
+      text: Spanned,
+      start: Int,
+      end: Int,
+      verticalOffset: Float,
+      calculatedLineCount: Int,
+      retList: ArrayList<Float>,
+  ) {
+    if (start < 0 || end < 0 || start >= end) {
+      return
+    }
+
+    // Get the bounding rect for this text range
+    // We need to handle multi-line text fragments by getting rects for each line
+    val startLine = layout.getLineForOffset(start)
+    val endLine = layout.getLineForOffset(end - 1)
+
+    for (line in startLine..min(endLine, calculatedLineCount - 1)) {
+      val lineStart = layout.getLineStart(line)
+      val lineEnd = layout.getLineEnd(line)
+
+      // Calculate the portion of this fragment on this line
+      val fragmentStartOnLine = max(start, lineStart)
+      val fragmentEndOnLine = min(end, lineEnd)
+
+      if (fragmentStartOnLine >= fragmentEndOnLine) {
+        continue
+      }
+
+      // Get the horizontal bounds
+      // For the left position, use getPrimaryHorizontal at the fragment start
+      val left = layout.getPrimaryHorizontal(fragmentStartOnLine)
+
+      // For the right position, we need to handle the case where the fragment
+      // ends at a line break. In this case, getPrimaryHorizontal at the end
+      // returns the same as at the start of the next line (or line start).
+      // Instead, we should use the line's right bound or the position just before
+      // the line end character.
+      val right: Float
+      if (fragmentEndOnLine >= lineEnd && lineEnd > lineStart) {
+        // Fragment goes to the end of the line - use the position before the newline
+        // or use getLineRight for the actual right edge of text on this line
+        right = layout.getLineRight(line)
+      } else {
+        right = layout.getPrimaryHorizontal(fragmentEndOnLine)
+      }
+
+      // Get the vertical bounds
+      val top = layout.getLineTop(line) + verticalOffset
+      val bottom = layout.getLineBottom(line) + verticalOffset
+
+      // Ensure left is less than right (RTL text handling)
+      val rectLeft = min(left, right)
+      val rectRight = max(left, right)
+
+      retList.add(rectLeft.pxToDp())
+      retList.add(top.pxToDp())
+      retList.add((rectRight - rectLeft).pxToDp())
+      retList.add((bottom - top).pxToDp())
+    }
+  }
+
   private fun getVerticalOffset(
       layout: Layout,
       paragraphAttributes: ReadableMapBuffer,

packages/react-native/ReactCommon/react/renderer/textlayoutmanager/platform/android/react/renderer/textlayoutmanager/TextLayoutManager.cpp

@@ -437,4 +437,93 @@ TextMeasurement TextLayoutManager::measurePreparedLayout(
   return textMeasurement;
 }
 
+std::vector<Rect> TextLayoutManager::getFragmentRectsForReactTag(
+    const PreparedLayout& preparedLayout,
+    Tag targetReactTag) const {
+  const auto& fabricUIManager =
+      contextContainer_->at<jni::global_ref<jobject>>("FabricUIManager");
+
+  static auto getFragmentRectsForReactTagMethod =
+      jni::findClassStatic("com/facebook/react/fabric/FabricUIManager")
+          ->getMethod<jni::JArrayFloat(JPreparedLayout::javaobject, jint)>(
+              "getFragmentRectsForReactTag");
+
+  auto rectsArr = getFragmentRectsForReactTagMethod(
+      fabricUIManager, preparedLayout.get(), targetReactTag);
+
+  std::vector<Rect> result;
+  if (rectsArr == nullptr || rectsArr->size() == 0) {
+    return result;
+  }
+
+  auto rects = rectsArr->getRegion(0, static_cast<jsize>(rectsArr->size()));
+
+  // The array contains [x, y, width, height] for each rect
+  react_native_assert(rectsArr->size() % 4 == 0);
+  result.reserve(rectsArr->size() / 4);
+
+  for (size_t i = 0; i < rectsArr->size(); i += 4) {
+    result.push_back(
+        Rect{
+            .origin = {.x = rects[i], .y = rects[i + 1]},
+            .size = {.width = rects[i + 2], .height = rects[i + 3]}});
+  }
+
+  return result;
+}
+
+std::vector<Rect> TextLayoutManager::getFragmentRectsFromAttributedString(
+    Tag surfaceId,
+    const AttributedString& attributedString,
+    const ParagraphAttributes& paragraphAttributes,
+    const LayoutConstraints& layoutConstraints,
+    Tag targetReactTag) const {
+  const auto& fabricUIManager =
+      contextContainer_->at<jni::global_ref<jobject>>("FabricUIManager");
+
+  static auto getFragmentRectsFromAttributedStringMethod =
+      jni::findClassStatic("com/facebook/react/fabric/FabricUIManager")
+          ->getMethod<jni::JArrayFloat(
+              jint,
+              JReadableMapBuffer::javaobject,
+              JReadableMapBuffer::javaobject,
+              jfloat,
+              jfloat,
+              jint)>("getFragmentRectsFromAttributedString");
+
+  auto attributedStringMB =
+      JReadableMapBuffer::createWithContents(toMapBuffer(attributedString));
+  auto paragraphAttributesMB =
+      JReadableMapBuffer::createWithContents(toMapBuffer(paragraphAttributes));
+
+  auto rectsArr = getFragmentRectsFromAttributedStringMethod(
+      fabricUIManager,
+      surfaceId,
+      attributedStringMB.get(),
+      paragraphAttributesMB.get(),
+      layoutConstraints.maximumSize.width,
+      layoutConstraints.maximumSize.height,
+      targetReactTag);
+
+  std::vector<Rect> result;
+  if (rectsArr == nullptr || rectsArr->size() == 0) {
+    return result;
+  }
+
+  auto rects = rectsArr->getRegion(0, static_cast<jsize>(rectsArr->size()));
+
+  // The array contains [x, y, width, height] for each rect
+  react_native_assert(rectsArr->size() % 4 == 0);
+  result.reserve(rectsArr->size() / 4);
+
+  for (size_t i = 0; i < rectsArr->size(); i += 4) {
+    result.push_back(
+        Rect{
+            .origin = {.x = rects[i], .y = rects[i + 1]},
+            .size = {.width = rects[i + 2], .height = rects[i + 3]}});
+  }
+
+  return result;
+}
+
 } // namespace facebook::react