Add support for animated effects on spans of text (facebook#56702)

Summary:
Pull Request resolved: facebook#56702

Adds `AnimatedEffectSpan`, a new span type for animated effects drawn on top
of text in `PreparedLayoutTextView`. Unlike `DrawCommandSpan` which provides
static `onPreDraw`/`onDraw` hooks, `AnimatedEffectSpan` supports animation via
a `requestAnimationFrame`-style API where the span receives a time delta each
frame and returns whether it wants another frame.

Key design decisions:
- Independent from `DrawCommandSpan` — does not subclass it
- Does not implement `UpdateAppearance` — animated effects don't affect text measurement or paint state
- Implements `ReactSpan` for integration with RN's span management
- Annotated `UnstableReactNativeAPI` — callers must opt in
- Zero overhead for non-animated text: delta computation and frame scheduling only happen when animated spans exist
- Frame timing resets on visibility changes and view recycling to prevent delta spikes

Changelog: [Internal]

Reviewed By: alanleedev

Differential Revision: D97399151

fbshipit-source-id: da2015c1b49d122c522dae5c49f6c83ca1979daf

Author: andrewdacenko

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

@@ -18,15 +18,18 @@ import android.text.Spanned
 import android.text.style.ClickableSpan
 import android.view.KeyEvent
 import android.view.MotionEvent
+import android.view.View
 import android.view.ViewGroup
 import androidx.annotation.ColorInt
 import androidx.annotation.DoNotInline
 import androidx.annotation.RequiresApi
 import androidx.core.view.ViewCompat
 import com.facebook.proguard.annotations.DoNotStrip
+import com.facebook.react.common.annotations.UnstableReactNativeAPI
 import com.facebook.react.uimanager.BackgroundStyleApplicator
 import com.facebook.react.uimanager.ReactCompoundView
 import com.facebook.react.uimanager.style.Overflow
+import com.facebook.react.views.text.internal.span.AnimatedEffectSpan
 import com.facebook.react.views.text.internal.span.DrawCommandSpan
 import com.facebook.react.views.text.internal.span.ReactFragmentIndexSpan
 import com.facebook.react.views.text.internal.span.ReactLinkSpan
@@ -44,6 +47,7 @@ internal class PreparedLayoutTextView(context: Context) : ViewGroup(context), Re
 
   private var clickableSpans: List<ClickableSpan> = emptyList()
   private var selection: TextSelection? = null
+  private var lastFrameTimeNanos: Long = 0L
 
   var preparedLayout: PreparedLayout? = null
     set(value) {
@@ -99,9 +103,18 @@ internal class PreparedLayoutTextView(context: Context) : ViewGroup(context), Re
     clickableSpans = emptyList()
     selection = null
     selectionColor = null
+    lastFrameTimeNanos = 0L
     preparedLayout = null
   }
 
+  override fun onVisibilityChanged(changedView: View, visibility: Int) {
+    super.onVisibilityChanged(changedView, visibility)
+    if (visibility != VISIBLE) {
+      lastFrameTimeNanos = 0L
+    }
+  }
+
+  @OptIn(UnstableReactNativeAPI::class)
   override fun onDraw(canvas: Canvas) {
     if (overflow != Overflow.VISIBLE) {
       BackgroundStyleApplicator.clipToPaddingBox(this, canvas)
@@ -151,6 +164,38 @@ internal class PreparedLayoutTextView(context: Context) : ViewGroup(context), Re
           )
         }
       }
+
+      if (spanned != null) {
+        val animatedEffectSpans =
+            spanned.getSpans(0, spanned.length, AnimatedEffectSpan::class.java)
+
+        if (animatedEffectSpans.isNotEmpty()) {
+          val now = System.nanoTime()
+          val deltaNanos = if (lastFrameTimeNanos == 0L) 0L else now - lastFrameTimeNanos
+          lastFrameTimeNanos = now
+
+          var needsNextFrame = false
+          for (span in animatedEffectSpans) {
+            if (
+                span.onDraw(
+                    spanned.getSpanStart(span),
+                    spanned.getSpanEnd(span),
+                    canvas,
+                    layout,
+                    deltaNanos,
+                )
+            ) {
+              needsNextFrame = true
+            }
+          }
+
+          if (needsNextFrame) {
+            postInvalidateOnAnimation()
+          } else {
+            lastFrameTimeNanos = 0L
+          }
+        }
+      }
     }
   }
 

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/views/text/internal/span/AnimatedEffectSpan.kt

@@ -0,0 +1,37 @@
+/*
+ * 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.views.text.internal.span
+
+import android.graphics.Canvas
+import android.text.Layout
+import com.facebook.react.common.annotations.UnstableReactNativeAPI
+
+/**
+ * A span which draws an animated effect on top of text. Each frame, [onDraw] is called with the
+ * time since the last frame. Return true to request another frame, false to stop animating.
+ */
+@UnstableReactNativeAPI
+public interface AnimatedEffectSpan : StatefulSpan {
+  /**
+   * Called each frame to draw an animated effect on top of text.
+   *
+   * @param start the start offset of this span within the text
+   * @param end the end offset of this span within the text
+   * @param canvas the canvas to draw on
+   * @param layout the text layout
+   * @param deltaNanos nanoseconds since the last frame, or 0 on the first frame
+   * @return true to request another frame, false to stop animating
+   */
+  public fun onDraw(
+      start: Int,
+      end: Int,
+      canvas: Canvas,
+      layout: Layout,
+      deltaNanos: Long,
+  ): Boolean
+}