Add HardwareBackPressEvent with native timestamp (#56295)

Summary:
Pull Request resolved: #56295

Changelog: [Android][Added] - Pass event object to `BackHandler` `hardwareBackPress` events to access timeStamp from native event.

BackHandler on Android emits the `hardwareBackPress` event with a `null`
payload — no timestamp or event data. This means there is no way for
handlers to know when the user actually pressed the back button, which
prevents accurate performance tracing for back navigations.

This diff:
- Sends `SystemClock.uptimeMillis()` as `timestamp` in the native
  `DeviceEventManagerModule.emitHardwareBackPressed()` event payload
- Creates a new `HardwareBackPressEvent` class extending the DOM `Event`
  class, which overrides the `timeStamp` getter to return the native
  timestamp (falling back to `performance.now()` if unavailable)
- Makes the public constructor throw `TypeError("Illegal constructor")`
  following the `PerformanceEntry` pattern
- Updates all BackHandler platform files (Android, iOS, macOS, Windows)
  and type definitions (Flow, TypeScript) to create and pass the event
  to handlers
- Updates the BackHandler mock to pass events in `mockPressBack`
- Adds Fantom integration tests for both `HardwareBackPressEvent` and
  `BackHandler`

Differential Revision: D98941079

Author: rubennorte

packages/react-native/Libraries/Utilities/BackHandler.android.js

@@ -9,18 +9,26 @@
  */
 
 import NativeDeviceEventManager from '../../Libraries/NativeModules/specs/NativeDeviceEventManager';
+import {setEventInitTimeStamp} from '../../src/private/webapis/dom/events/internals/EventInternals';
 import RCTDeviceEventEmitter from '../EventEmitter/RCTDeviceEventEmitter';
+import {HardwareBackPressEvent} from './HardwareBackPressEvent';
 
 const DEVICE_BACK_EVENT = 'hardwareBackPress';
 
 type BackPressEventName = 'backPress' | 'hardwareBackPress';
-type BackPressHandler = () => ?boolean;
+type BackPressHandler = (event: HardwareBackPressEvent) => ?boolean;
 
 const _backPressSubscriptions: Array<BackPressHandler> = [];
 
-RCTDeviceEventEmitter.addListener(DEVICE_BACK_EVENT, function () {
+RCTDeviceEventEmitter.addListener(DEVICE_BACK_EVENT, function (nativeEvent) {
+  const options = {};
+  const nativeTimestamp = nativeEvent?.timeStamp;
+  if (nativeTimestamp != null) {
+    setEventInitTimeStamp(options, nativeTimestamp);
+  }
+  const event = new HardwareBackPressEvent(options);
   for (let i = _backPressSubscriptions.length - 1; i >= 0; i--) {
-    if (_backPressSubscriptions[i]?.()) {
+    if (_backPressSubscriptions[i]?.(event)) {
       return;
     }
   }

packages/react-native/Libraries/Utilities/BackHandler.d.ts

@@ -11,6 +11,16 @@ import {NativeEventSubscription} from '../EventEmitter/RCTNativeAppEventEmitter'
 
 export type BackPressEventName = 'hardwareBackPress';
 
+/**
+ * Event dispatched when the hardware back button is pressed.
+ * The `timeStamp` property reflects the native timestamp captured
+ * when the back press was emitted.
+ */
+export interface HardwareBackPressEvent {
+  readonly type: string;
+  readonly timeStamp: number;
+}
+
 /**
  * Detect hardware back button presses, and programmatically invoke the
  * default back button functionality to exit the app if there are no
@@ -26,7 +36,7 @@ export interface BackHandlerStatic {
   exitApp(): void;
   addEventListener(
     eventName: BackPressEventName,
-    handler: () => boolean | null | undefined,
+    handler: (event: HardwareBackPressEvent) => boolean | null | undefined,
   ): NativeEventSubscription;
 }
 

packages/react-native/Libraries/Utilities/BackHandler.ios.js

@@ -8,8 +8,10 @@
  * @format
  */
 
+import type {HardwareBackPressEvent} from './HardwareBackPressEvent';
+
 type BackPressEventName = 'backPress' | 'hardwareBackPress';
-type BackPressHandler = () => ?boolean;
+type BackPressHandler = (event: HardwareBackPressEvent) => ?boolean;
 
 function emptyFunction(): void {}
 

packages/react-native/Libraries/Utilities/BackHandler.js.flow

@@ -10,13 +10,17 @@
 
 'use strict';
 
+import type {HardwareBackPressEvent} from './HardwareBackPressEvent';
+
 export type BackPressEventName = 'backPress' | 'hardwareBackPress';
 
+export type {HardwareBackPressEvent} from './HardwareBackPressEvent';
+
 type TBackHandler = {
   exitApp(): void,
   addEventListener(
     eventName: BackPressEventName,
-    handler: () => ?boolean,
+    handler: (event: HardwareBackPressEvent) => ?boolean,
   ): {remove: () => void, ...},
 };
 

packages/react-native/Libraries/Utilities/HardwareBackPressEvent.js

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import type {EventInit} from '../../src/private/webapis/dom/events/Event';
+
+import Event from '../../src/private/webapis/dom/events/Event';
+
+/**
+ * Event dispatched when the hardware back button is pressed on Android.
+ */
+export class HardwareBackPressEvent extends Event {
+  constructor(options?: ?EventInit) {
+    super('hardwareBackPress', options);
+  }
+}

packages/react-native/Libraries/Utilities/__mocks__/BackHandler.js

@@ -9,15 +9,20 @@
  */
 
 import type {BackPressEventName} from '../BackHandler';
+import type {HardwareBackPressEvent} from '../HardwareBackPressEvent';
 
-const _backPressSubscriptions = new Set<() => ?boolean>();
+import {HardwareBackPressEvent as HardwareBackPressEventClass} from '../HardwareBackPressEvent';
+
+const _backPressSubscriptions = new Set<
+  (event: HardwareBackPressEvent) => ?boolean,
+>();
 
 const BackHandler = {
   exitApp: jest.fn() as () => void,
 
   addEventListener: function (
     eventName: BackPressEventName,
-    handler: () => ?boolean,
+    handler: (event: HardwareBackPressEvent) => ?boolean,
   ): {remove: () => void, ...} {
     _backPressSubscriptions.add(handler);
     return {
@@ -28,10 +33,11 @@ const BackHandler = {
   },
 
   mockPressBack: function () {
+    const event = new HardwareBackPressEventClass();
     let invokeDefault = true;
     const subscriptions = [..._backPressSubscriptions].reverse();
     for (let i = 0; i < subscriptions.length; ++i) {
-      if (subscriptions[i]()) {
+      if (subscriptions[i](event)) {
         invokeDefault = false;
         break;
       }

packages/react-native/Libraries/Utilities/__tests__/BackHandler-itest.js

@@ -0,0 +1,144 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
+
+import type {HardwareBackPressEvent} from 'react-native/Libraries/Utilities/HardwareBackPressEvent';
+
+import RCTDeviceEventEmitter from 'react-native/Libraries/EventEmitter/RCTDeviceEventEmitter';
+import BackHandler from 'react-native/Libraries/Utilities/BackHandler';
+import {HardwareBackPressEvent as HardwareBackPressEventClass} from 'react-native/Libraries/Utilities/HardwareBackPressEvent';
+
+describe('BackHandler', () => {
+  const subscriptions: Array<{remove: () => void, ...}> = [];
+
+  afterEach(() => {
+    for (const sub of subscriptions) {
+      sub.remove();
+    }
+    subscriptions.length = 0;
+  });
+
+  it('calls handlers in reverse order (LIFO)', () => {
+    const callOrder: Array<string> = [];
+    const handler1 = (_event: HardwareBackPressEvent) => {
+      callOrder.push('first');
+      return false;
+    };
+    const handler2 = (_event: HardwareBackPressEvent) => {
+      callOrder.push('second');
+      return true;
+    };
+
+    subscriptions.push(
+      BackHandler.addEventListener('hardwareBackPress', handler1),
+    );
+    subscriptions.push(
+      BackHandler.addEventListener('hardwareBackPress', handler2),
+    );
+
+    RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 100});
+
+    expect(callOrder).toEqual(['second']);
+  });
+
+  it('calls all handlers when none return true', () => {
+    const callOrder: Array<string> = [];
+    const handler1 = (_event: HardwareBackPressEvent) => {
+      callOrder.push('first');
+      return false;
+    };
+    const handler2 = (_event: HardwareBackPressEvent) => {
+      callOrder.push('second');
+      return false;
+    };
+
+    subscriptions.push(
+      BackHandler.addEventListener('hardwareBackPress', handler1),
+    );
+    subscriptions.push(
+      BackHandler.addEventListener('hardwareBackPress', handler2),
+    );
+
+    RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 100});
+
+    expect(callOrder).toEqual(['second', 'first']);
+  });
+
+  it('passes HardwareBackPressEvent to handlers', () => {
+    let receivedEvent: ?HardwareBackPressEvent = null;
+    const handler = (event: HardwareBackPressEvent) => {
+      receivedEvent = event;
+      return true;
+    };
+
+    subscriptions.push(
+      BackHandler.addEventListener('hardwareBackPress', handler),
+    );
+
+    RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 42});
+
+    expect(receivedEvent).toBeInstanceOf(HardwareBackPressEventClass);
+  });
+
+  it('event has native timestamp as timeStamp', () => {
+    let receivedEvent: ?HardwareBackPressEvent = null;
+    const handler = (event: HardwareBackPressEvent) => {
+      receivedEvent = event;
+      return true;
+    };
+
+    subscriptions.push(
+      BackHandler.addEventListener('hardwareBackPress', handler),
+    );
+
+    RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 42});
+
+    expect(receivedEvent?.timeStamp).toBe(42);
+  });
+
+  it('event falls back to performance.now() when no native timestamp', () => {
+    let receivedEvent: ?HardwareBackPressEvent = null;
+    const handler = (event: HardwareBackPressEvent) => {
+      receivedEvent = event;
+      return true;
+    };
+
+    subscriptions.push(
+      BackHandler.addEventListener('hardwareBackPress', handler),
+    );
+
+    const before = performance.now();
+    RCTDeviceEventEmitter.emit('hardwareBackPress', null);
+    const after = performance.now();
+
+    const timeStamp = receivedEvent?.timeStamp;
+    expect(timeStamp).not.toBeNull();
+    if (timeStamp != null) {
+      expect(timeStamp).toBeGreaterThanOrEqual(before);
+      expect(timeStamp).toBeLessThanOrEqual(after);
+    }
+  });
+
+  it('removes handler on subscription.remove()', () => {
+    let called = false;
+    const handler = (_event: HardwareBackPressEvent) => {
+      called = true;
+      return true;
+    };
+
+    const sub = BackHandler.addEventListener('hardwareBackPress', handler);
+    sub.remove();
+
+    RCTDeviceEventEmitter.emit('hardwareBackPress', {timeStamp: 100});
+
+    expect(called).toBe(false);
+  });
+});

packages/react-native/Libraries/Utilities/__tests__/HardwareBackPressEvent-itest.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
+
+import {HardwareBackPressEvent} from 'react-native/Libraries/Utilities/HardwareBackPressEvent';
+import Event from 'react-native/src/private/webapis/dom/events/Event';
+import {setEventInitTimeStamp} from 'react-native/src/private/webapis/dom/events/internals/EventInternals';
+
+describe('HardwareBackPressEvent', () => {
+  it('extends Event', () => {
+    const event = new HardwareBackPressEvent();
+
+    expect(event).toBeInstanceOf(Event);
+    expect(event.type).toBe('hardwareBackPress');
+    expect(event.bubbles).toBe(false);
+    expect(event.cancelable).toBe(false);
+    expect(event.composed).toBe(false);
+  });
+
+  it('uses native timestamp as timeStamp when provided via setEventInitTimeStamp', () => {
+    const options = {};
+    setEventInitTimeStamp(options, 12345);
+    const event = new HardwareBackPressEvent(options);
+
+    expect(event.timeStamp).toBe(12345);
+  });
+
+  it('falls back to performance.now() when no timestamp is provided', () => {
+    const before = performance.now();
+    const event = new HardwareBackPressEvent();
+    const after = performance.now();
+
+    expect(event.timeStamp).toBeGreaterThanOrEqual(before);
+    expect(event.timeStamp).toBeLessThanOrEqual(after);
+  });
+
+  it('falls back to performance.now() when options is undefined', () => {
+    const before = performance.now();
+    const event = new HardwareBackPressEvent(undefined);
+    const after = performance.now();
+
+    expect(event.timeStamp).toBeGreaterThanOrEqual(before);
+    expect(event.timeStamp).toBeLessThanOrEqual(after);
+  });
+
+  it('does NOT allow changing the timeStamp value after construction', () => {
+    const options = {};
+    setEventInitTimeStamp(options, 12345);
+    const event = new HardwareBackPressEvent(options);
+
+    expect(() => {
+      'use strict';
+      // $FlowExpectedError[cannot-write]
+      event.timeStamp = 999;
+    }).toThrow();
+  });
+});

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/core/DeviceEventManagerModule.kt

@@ -36,7 +36,8 @@ public open class DeviceEventManagerModule(
   public open fun emitHardwareBackPressed() {
     val reactApplicationContext: ReactApplicationContext? =
         getReactApplicationContextIfActiveOrWarn()
-    reactApplicationContext?.emitDeviceEvent("hardwareBackPress", null)
+    val map = buildReadableMap { put("timeStamp", System.nanoTime() / 1_000_000.0) }
+    reactApplicationContext?.emitDeviceEvent("hardwareBackPress", map)
   }
 
   /** Sends an event to the JS instance that a new intent was received. */