Fix Animated listeners on nodes derived from Animated.Value (#58037)

Summary:
Fixes #49719.

`addListener` stopped firing on any `AnimatedNode` *derived* from an `Animated.Value` — `Animated.add`/`subtract`/`multiply`/`divide`/`modulo`/`diffClamp` and `.interpolate()` — for natively driven animations. It worked in 0.77 and regressed in 0.78. The issue has since been reported for both `Animated.add` and `.interpolate()`, on both architectures, and the only workaround is to listen to the source value and recompute the derived value in JS — which observes intermediate values that never reach the screen.

There are two independent causes.

### 1. JS: derived nodes never subscribe to native updates

Before 38c46fe ("Animated: Lower `onAnimatedValueUpdate` to `AnimatedValue`", #48514), `AnimatedNode.addListener` called `startListeningToAnimatedNodeValue` for any node that had been made native. That commit moved the logic down into `AnimatedValue`, on the premise that:

> the `startListeningToAnimatedNodeValue` native module method only supports native tags for instances of `AnimatedValue` […] On Android, `startListeningToAnimatedNodeValue` throws if the node is not an instance of `ValueAnimatedNode`. On iOS, it does nothing if node is not an instance of `RCTValueAnimatedNode`.

That holds for props/style/transform/object/tracking/color nodes, but not for the operator and interpolation nodes, which *are* value nodes natively:

- **Android** — `AdditionAnimatedNode`, `SubtractionAnimatedNode`, `MultiplicationAnimatedNode`, `DivisionAnimatedNode`, `ModulusAnimatedNode`, `DiffClampAnimatedNode` and `InterpolationAnimatedNode` all extend `ValueAnimatedNode`, and `NativeAnimatedNodesManager` checks `node !is ValueAnimatedNode`.
- **iOS** — the corresponding `RCT*AnimatedNode` classes all inherit `RCTValueAnimatedNode`, and the manager checks `isKindOfClass:[RCTValueAnimatedNode class]`.

So the subscription was dropped for a set of nodes that natively support it. This restores it on `AnimatedNode`, gated on a new `__isNativeValueNode` flag that is `true` only for nodes backed by a native value node. That keeps the guarantee #48514 was after — never call `startListeningToAnimatedNodeValue` with a non-value tag — but states it explicitly instead of leaving it implicit in the class hierarchy. `AnimatedValue` now inherits that machinery rather than duplicating it.

`AnimatedNode.__detach` also drops the subscription before `dropAnimatedNode`, so it can never outlive the tag it observes.

### 2. C++: `startListeningToAnimatedNodeValue` rejects derived value nodes

Unlike Android and iOS, the C++ backend used by the New Architecture compares the node's *exact* type tag instead of testing for a `ValueAnimatedNode` subclass:

```c++
iter->second->type() == AnimatedNodeType::Value
```

so an addition or interpolation node was rejected with `"does not exist, or is not a 'value' node"`, even though `static_cast<ValueAnimatedNode*>` would have been valid. Replaced with an exhaustive `isValueNodeType` predicate, so every node type whose C++ class derives from `ValueAnimatedNode` (including `Round`) is accepted and the non-value ones are still rejected.

`AnimatedNode.__onAnimatedValueUpdateReceived` had to accept a missing `offset` as well: the C++ backend emits `onAnimatedValueUpdate` without one, which would otherwise produce `NaN` (`value + undefined`).

## Changelog:

[GENERAL] [FIXED] - `addListener` fires again for natively driven `Animated` values derived with `add`/`subtract`/`multiply`/`divide`/`modulo`/`diffClamp`/`interpolate`

Pull Request resolved: #58037

Test Plan:
### New tests

**`Libraries/Animated/__tests__/AnimatedComposition-itest.js`** — renders a derived node bound to `translateX`, attaches a listener to the *derived* node before it is made native, runs a `timing` animation on the source value, and asserts the listener observed the derived value; then asserts `removeListener` stops the updates. Parameterised over the five operators plus `interpolate`, and over both drivers.

**`ReactCommon/react/renderer/animated/tests/AnimatedNodeTests.cpp`** — `StartListeningToDerivedValueNode` asserts the C++ backend delivers updates for an `addition` node and stops on `stopListeningToAnimatedNodeValue`. `StartListeningToNonValueNodeIsIgnored` asserts registering on a `transform` node is still a no-op.

### Results

```
$ yarn fantom packages/react-native/Libraries/Animated/__tests__/AnimatedComposition-itest.js
  addListener on derived value nodes
    ✓ Animated.add notifies its listeners on the JS driver
    ✓ Animated.subtract notifies its listeners on the JS driver
    ✓ Animated.multiply notifies its listeners on the JS driver
    ✓ Animated.divide notifies its listeners on the JS driver
    ✓ Animated.modulo notifies its listeners on the JS driver
    ✓ interpolate notifies its listeners on the JS driver
    ✓ Animated.add notifies its listeners on the native driver
    ✓ Animated.subtract notifies its listeners on the native driver
    ✓ Animated.multiply notifies its listeners on the native driver
    ✓ Animated.divide notifies its listeners on the native driver
    ✓ Animated.modulo notifies its listeners on the native driver
    ✓ interpolate notifies its listeners on the native driver

Tests: 26 passed, 26 total
```

Reverting only the fix (keeping the new test) fails exactly the six `native driver` cases, which is the reported bug; the `JS driver` cases were never broken:

```
✕ Animated.add notifies its listeners on the native driver
  Expected 0 to be greater than or equal to 0
  > 469 |         expect(values.length).toBeGreaterThan(0);
…
Tests: 6 failed, 20 passed, 26 total
```

No regressions in the rest of the Animated suite:

```
$ yarn fantom packages/react-native/Libraries/Animated/__tests__/
Test Suites: 2 skipped, 16 passed, 16 of 18 total
Tests:       3 skipped, 297 passed, 300 total

$ yarn jest packages/react-native/Libraries/Animated
Test Suites: 3 passed, 3 total
Tests:       66 passed, 66 total

$ yarn flow-check
Found 0 errors

$ yarn lint     # changed files
(no output)
```

`yarn build-types` regenerated `ReactNativeApi.d.ts`; the only substantive change is that `AnimatedValue`'s `removeListener`/`removeAllListeners` are now inherited from `AnimatedNode` rather than redeclared. `addListener` keeps its narrower `ValueListenerCallback` signature.

Correction to an earlier revision of this description: the C++ tests were not run locally, and they are not covered by the public CI either. `react/renderer/animated/tests` is excluded from the iOS build (`React-Fabric.podspec`: `ss.exclude_files = "react/renderer/animated/tests"`) and is not in the Android CMake glob (`react/renderer/animated/CMakeLists.txt` globs `*.cpp drivers/*.cpp event_drivers/*.cpp internal/*.cpp nodes/*.cpp`), so they build only in the internal build reached at import time. What is verified here: `NativeAnimatedNodesManager.cpp` compiles clean under `-Wall -Werror -Wpedantic` as part of the Fantom tester build, and the JS-side changes are covered by the Fantom and Jest runs above.

### Notes

For a colour `interpolate()` on the native driver the listener receives the interpolated colour as a number rather than a string, because the value is computed natively. That matches pre-0.78 behaviour and is out of scope here.

Reviewed By: christophpurrer, cipolleschi

Differential Revision: D117209945

Pulled By: zeyap

fbshipit-source-id: b50657a7b2d25e10e980b43cb1e9e1f1db5f3906

Author: dennytosp

packages/react-native/Libraries/Animated/__tests__/AnimatedComposition-itest.js

@@ -379,3 +379,124 @@ describe('composition nodes: native driver, interpolation and detach', () => {
     });
   }
 });
+
+// Regression test for https://github.com/facebook/react-native/issues/49719.
+// Listeners attached to a node *derived* from an `Animated.Value` (an operator
+// or an interpolation) must keep firing, on both drivers. On the native driver
+// the value is computed natively, so the derived node has to subscribe to
+// native updates for its own tag rather than relying on the JS graph.
+describe('addListener on derived value nodes', () => {
+  const derivedNodes = [
+    {
+      name: 'Animated.add',
+      make: (base: Animated.Value) => Animated.add(base, 10),
+      expected: 60,
+    },
+    {
+      name: 'Animated.subtract',
+      make: (base: Animated.Value) => Animated.subtract(base, 10),
+      expected: 40,
+    },
+    {
+      name: 'Animated.multiply',
+      make: (base: Animated.Value) => Animated.multiply(base, 2),
+      expected: 100,
+    },
+    {
+      name: 'Animated.divide',
+      make: (base: Animated.Value) => Animated.divide(base, 2),
+      expected: 25,
+    },
+    {
+      name: 'Animated.modulo',
+      make: (base: Animated.Value) => Animated.modulo(base, 7),
+      expected: 50 % 7,
+    },
+    {
+      // Accumulates the delta of its input and clamps it: as `base` climbs
+      // from 0 to 50 the accumulated delta saturates at `max`.
+      name: 'Animated.diffClamp',
+      make: (base: Animated.Value) => Animated.diffClamp(base, 0, 20),
+      expected: 20,
+    },
+    {
+      name: 'interpolate',
+      make: (base: Animated.Value) =>
+        base.interpolate({inputRange: [0, 50], outputRange: [0, 500]}),
+      expected: 500,
+    },
+  ];
+
+  for (const useNativeDriver of [false, true]) {
+    const driverName = useNativeDriver ? 'native driver' : 'JS driver';
+
+    for (const {name, make, expected} of derivedNodes) {
+      it(`${name} notifies its listeners on the ${driverName}`, () => {
+        let base: ?Animated.Value;
+        let node: ?Animated.Node;
+
+        function MyApp() {
+          const value = useAnimatedValue(0);
+          base = value;
+          node = make(value);
+          return (
+            <Animated.View
+              style={[
+                {width: 100, height: 100},
+                {transform: [{translateX: node}]},
+              ]}
+            />
+          );
+        }
+
+        const root = Fantom.createRoot();
+        Fantom.runTask(() => {
+          root.render(<MyApp />);
+        });
+
+        // The listener is attached before the node is made native, so this
+        // also covers the subscription being created from `__makeNative`. The
+        // opposite order — attaching once the node is already native — is
+        // covered per node type by AnimatedNative-test.
+        const values: Array<number> = [];
+        const listenerId = nullthrows(node).addListener(state => {
+          values.push(state.value);
+        });
+
+        let animation: ?Animated.CompositeAnimation;
+        Fantom.runTask(() => {
+          animation = Animated.timing(nullthrows(base), {
+            toValue: 50,
+            duration: 100,
+            useNativeDriver,
+          });
+          animation.start();
+        });
+        Fantom.unstable_produceFramesForDuration(200);
+        Fantom.runWorkLoop();
+
+        expect(values.length).toBeGreaterThan(0);
+        expect(values[values.length - 1]).toBeCloseTo(expected, 0);
+
+        // Removing the listener stops the updates.
+        nullthrows(node).removeListener(listenerId);
+        const countAfterRemoval = values.length;
+        Fantom.runTask(() => {
+          nullthrows(base).setValue(0);
+        });
+        Fantom.unstable_produceFramesForDuration(32);
+        Fantom.runWorkLoop();
+        expect(values.length).toBe(countAfterRemoval);
+
+        Fantom.runTask(() => {
+          nullthrows(animation).stop();
+        });
+        Fantom.runTask(() => {
+          root.render(<Animated.View style={{width: 1, height: 1}} />);
+        });
+        Fantom.unstable_produceFramesForDuration(16);
+        Fantom.runWorkLoop();
+      });
+    }
+  }
+});

packages/react-native/Libraries/Animated/nodes/AnimatedAddition.js

@@ -20,6 +20,8 @@ import AnimatedValue from './AnimatedValue';
 import AnimatedWithChildren from './AnimatedWithChildren';
 
 export default class AnimatedAddition extends AnimatedWithChildren {
+  __isNativeValueNode: boolean = true;
+
   _a: AnimatedNode;
   _b: AnimatedNode;
 

packages/react-native/Libraries/Animated/nodes/AnimatedDiffClamp.js

@@ -19,6 +19,8 @@ import AnimatedInterpolation from './AnimatedInterpolation';
 import AnimatedWithChildren from './AnimatedWithChildren';
 
 export default class AnimatedDiffClamp extends AnimatedWithChildren {
+  __isNativeValueNode: boolean = true;
+
   _a: AnimatedNode;
   _min: number;
   _max: number;

packages/react-native/Libraries/Animated/nodes/AnimatedDivision.js

@@ -20,6 +20,8 @@ import AnimatedValue from './AnimatedValue';
 import AnimatedWithChildren from './AnimatedWithChildren';
 
 export default class AnimatedDivision extends AnimatedWithChildren {
+  __isNativeValueNode: boolean = true;
+
   _a: AnimatedNode;
   _b: AnimatedNode;
   _warnedAboutDivideByZero: boolean = false;

packages/react-native/Libraries/Animated/nodes/AnimatedInterpolation.js

@@ -444,6 +444,8 @@ function sampleEasingStops(
 export default class AnimatedInterpolation<
   OutputT extends InterpolationConfigSupportedOutputType,
 > extends AnimatedWithChildren {
+  __isNativeValueNode: boolean = true;
+
   _parent: AnimatedNode;
   _config: InterpolationConfigType<OutputT>;
   _interpolation: ?(input: number) => OutputT;

packages/react-native/Libraries/Animated/nodes/AnimatedModulo.js

@@ -19,6 +19,8 @@ import AnimatedInterpolation from './AnimatedInterpolation';
 import AnimatedWithChildren from './AnimatedWithChildren';
 
 export default class AnimatedModulo extends AnimatedWithChildren {
+  __isNativeValueNode: boolean = true;
+
   _a: AnimatedNode;
   _modulus: number;
 

packages/react-native/Libraries/Animated/nodes/AnimatedMultiplication.js

@@ -20,6 +20,8 @@ import AnimatedValue from './AnimatedValue';
 import AnimatedWithChildren from './AnimatedWithChildren';
 
 export default class AnimatedMultiplication extends AnimatedWithChildren {
+  __isNativeValueNode: boolean = true;
+
   _a: AnimatedNode;
   _b: AnimatedNode;
 

packages/react-native/Libraries/Animated/nodes/AnimatedNode.js

@@ -8,6 +8,7 @@
  * @format
  */
 
+import type {EventSubscription} from '../../vendor/emitter/EventEmitter';
 import type {PlatformConfig} from '../AnimatedPlatformConfig';
 
 import NativeAnimatedHelper from '../../../src/private/animated/NativeAnimatedHelper';
@@ -54,7 +55,12 @@ export default class AnimatedNode {
       this.removeAllListeners();
     }
     if (this.__isNative && this.__nativeTag != null) {
-      NativeAnimatedHelper.API.dropAnimatedNode(this.__nativeTag);
+      const nativeTag = this.__nativeTag;
+      // The subscription must not outlive the native tag it observes. Any
+      // listeners kept around are re-subscribed by `__makeNative` if this node
+      // is attached again.
+      this.__updateSubscription?.remove();
+      NativeAnimatedHelper.API.dropAnimatedNode(nativeTag);
       this.__nativeTag = undefined;
     }
   }
@@ -73,6 +79,19 @@ export default class AnimatedNode {
   __nativeTag: ?number = undefined;
   __disableBatchingForNativeCreate: ?boolean = undefined;
 
+  /**
+   * Whether the native node backing this one holds a number, and therefore
+   * supports `startListeningToAnimatedNodeValue`. That native module method
+   * only accepts tags of "value" nodes (`ValueAnimatedNode` on Android and in
+   * C++, `RCTValueAnimatedNode` on iOS); passing any other tag throws on
+   * Android and is a no-op elsewhere.
+   *
+   * Subclasses backed by a non-value native node — props, style, transform,
+   * object, tracking and color — must leave this `false`.
+   */
+  __isNativeValueNode: boolean = false;
+  __updateSubscription: ?EventSubscription = null;
+
   __makeNative(platformConfig: ?PlatformConfig): void {
     // Subclasses are expected to set `__isNative` to true before this.
     invariant(
@@ -81,6 +100,9 @@ export default class AnimatedNode {
     );
 
     this._platformConfig = platformConfig;
+    if (this._listeners.size > 0) {
+      this.__ensureUpdateSubscriptionExists();
+    }
   }
 
   /**
@@ -93,6 +115,9 @@ export default class AnimatedNode {
   addListener(callback: (value: any) => unknown): string {
     const id = String(_uniqueId++);
     this._listeners.set(id, callback);
+    if (this.__isNative) {
+      this.__ensureUpdateSubscriptionExists();
+    }
     return id;
   }
 
@@ -104,6 +129,9 @@ export default class AnimatedNode {
    */
   removeListener(id: string): void {
     this._listeners.delete(id);
+    if (this.__isNative && this._listeners.size === 0) {
+      this.__updateSubscription?.remove();
+    }
   }
 
   /**
@@ -113,14 +141,53 @@ export default class AnimatedNode {
    */
   removeAllListeners(): void {
     this._listeners.clear();
+    if (this.__isNative) {
+      this.__updateSubscription?.remove();
+    }
   }
 
   hasListeners(): boolean {
     return this._listeners.size > 0;
   }
 
-  __onAnimatedValueUpdateReceived(value: number, offset: number): void {
-    this.__callListeners(value + offset);
+  /**
+   * Subscribes to native updates of this node's value, so that listeners keep
+   * firing for natively driven animations. No-op for nodes that are not backed
+   * by a native "value" node.
+   */
+  __ensureUpdateSubscriptionExists(): void {
+    if (!this.__isNativeValueNode || this.__updateSubscription != null) {
+      return;
+    }
+    const nativeTag = this.__getNativeTag();
+    NativeAnimatedHelper.API.startListeningToAnimatedNodeValue(nativeTag);
+    const subscription: EventSubscription =
+      NativeAnimatedHelper.nativeEventEmitter.addListener(
+        'onAnimatedValueUpdate',
+        data => {
+          if (data.tag === nativeTag) {
+            this.__onAnimatedValueUpdateReceived(data.value, data.offset);
+          }
+        },
+      );
+
+    this.__updateSubscription = {
+      remove: () => {
+        // Only this function assigns to `this.__updateSubscription`.
+        if (this.__updateSubscription == null) {
+          return;
+        }
+        this.__updateSubscription = null;
+        subscription.remove();
+        NativeAnimatedHelper.API.stopListeningToAnimatedNodeValue(nativeTag);
+      },
+    };
+  }
+
+  // NOTE: only Android sends an `offset`; iOS and the C++ backend omit it and
+  // report a value that already accounts for one.
+  __onAnimatedValueUpdateReceived(value: number, offset?: ?number): void {
+    this.__callListeners(value + (offset ?? 0));
   }
 
   __callListeners(value: number): void {

packages/react-native/Libraries/Animated/nodes/AnimatedSubtraction.js

@@ -20,6 +20,8 @@ import AnimatedValue from './AnimatedValue';
 import AnimatedWithChildren from './AnimatedWithChildren';
 
 export default class AnimatedSubtraction extends AnimatedWithChildren {
+  __isNativeValueNode: boolean = true;
+
   _a: AnimatedNode;
   _b: AnimatedNode;