feat: modern userEvent.press (#1949)

Author: mdjastrzebski

contributing/event-dispatch.md

@@ -11,17 +11,16 @@ The files in `src/events/legacy/`:
 | `fire-event.ts`  | Public `fireEvent` API                                                                                    |
 | `propagation.ts` | Bubbling vs direct events, walking up host and composite elements                                         |
 | `is-enabled.ts`  | Whether a device would deliver the event: `pointerEvents`, `editable`, touch responders                   |
-| `dispatch.ts`    | `dispatchEvent()`: calls the target's own handler in `act()`, used by `userEvent`                         |
 | `warnings.ts`    | `eventDiagnostics` warnings for `fireEvent`                                                               |
 | `builders/`      | Legacy event objects: `wrapNativeEvent()` (stubs from `baseSyntheticEvent()`), touch and responder events |
 
 Code used by both event systems lives in `src/events/shared/`: `handler.ts` (finding the `on*` handler for an event name in props), `native-state.ts` and `update-native-state.ts` ([native state](native-state.md) and how `fireEvent` updates it), `payloads.ts` (`nativeEvent` payloads matching what React Native sends on a device), `merge.ts` (deep merging custom props into them), `pointer-events.ts` (whether `pointerEvents` lets an element be the target of touches), `warnings.ts` (formatting and logging `eventDiagnostics` warnings, used by legacy `fireEvent` and `userEvent`), and `types.ts`.
 
-In the modern event system, `src/events/modern/pressability.ts` calls the `onPress`, `onPressIn`, `onPressOut` or `onLongPress` callback of the element that becomes the touch responder, reading `Pressable` and `Touchable*` callbacks from Pressability's `testOnly_pressabilityConfig()`. These callbacks aren't native events, so modern `fireEvent` sends the event types in `PRESSABILITY_EVENT_TYPES` (`src/events/modern/event-types.ts`) there instead of to `dispatchEvent()`: `fireEvent.press()`, and `fireEvent()` with `press`, `pressIn`, `pressOut` or `longPress`. `dispatchEvent()` still dispatches the native `press` event, which reaches only host `onPress` props.
+In the modern event system, `src/events/modern/pressability.ts` calls the `onPress`, `onPressIn`, `onPressOut` or `onLongPress` callback of the element that becomes the touch responder, reading `Pressable` and `Touchable*` callbacks from Pressability's `testOnly_pressabilityConfig()`. These callbacks aren't native events, so modern `fireEvent` sends the event types in `PRESSABILITY_EVENT_TYPES` (`src/events/modern/event-types.ts`) there instead of to `dispatchEvent()`: `fireEvent.press()`, and `fireEvent()` with `press`, `pressIn`, `pressOut` or `longPress`. `dispatchEvent()` still dispatches the native `press` event, which reaches only host `onPress` props. The callbacks get a `ResponderEvent` from `src/events/modern/responder-event.ts`, like React Native's responder system creates in JavaScript: `responderGrant` or `responderRelease`, with a touch payload, but no `touchHistory`, which only `PanResponder` reads. It isn't trusted, has no event phase or composed path, and has a `null` `currentTarget` in `onLongPress`, which Pressability calls from a timer.
 
 Modern `fireEvent` doesn't log `eventDiagnostics` warnings yet. Only legacy `fireEvent` and `userEvent` do.
 
-`src/user-event/` is a separate module on top of the event subsystem. It creates and dispatches native events through the facades `src/events/create-event.ts` and `src/events/dispatch-event.ts`. Legacy helpers (touch and responder event builders) come from `src/events/legacy/index.ts`, which also re-exports `src/events/shared/handler.ts`, `src/events/shared/native-state.ts` and `isPointerEventEnabled()`. Other code imports `src/events/modern/` and `src/events/shared/` modules directly: `src/user-event/modern/press.ts` (hit testing and responder negotiation from `pressability.ts`, handler lookup from `handler.ts`) and `src/user-event/utils/` (`invokeEventHandler()`, the `SyntheticEvent` type and the warning helpers from `warnings.ts`).
+`src/user-event/` is a separate module on top of the event subsystem. It creates and dispatches native events through the facades `src/events/create-event.ts` and `src/events/dispatch-event.ts`. For a legacy event object, `dispatchEvent()` calls the target's own handler with `invokeEventHandler()` from `src/events/shared/invoke-event-handler.ts`. Other modules are imported directly: legacy touch and responder event builders from `src/events/legacy/builders/common.ts`, and `src/events/modern/` and `src/events/shared/` modules, e.g. `src/user-event/modern/press.ts` (hit testing and responder negotiation from `pressability.ts`, handler lookup from `handler.ts`) and `src/user-event/utils/` (`invokeEventHandler()`, the `SyntheticEvent` type and the warning helpers from `warnings.ts`).
 
 ## `fireEvent`
 
@@ -37,7 +36,7 @@ Modern `fireEvent` doesn't log `eventDiagnostics` warnings yet. Only legacy `fir
 
 Each step dispatches a native event, created for the configured event system by `createEvent()` (`src/events/create-event.ts`: a legacy event object or a `SyntheticEvent`) and dispatched by `dispatchEvent()` (`src/events/dispatch-event.ts`), or calls a JavaScript callback (`changeText`, `pressIn`, ...) with `invokeEventHandler()`, which only calls the target's own handler. Modern `fireEvent.changeText()` instead calls `onChangeText` from the `change` dispatch, through `dispatchEvent()`'s `afterTargetHandler` option, right after the input's own `onChange`, where `TextInput` calls it. Neither checks whether the element is enabled. Each action does those checks itself, so the rules for an interaction live in one place.
 
-Where the two event systems need different rules, the action picks them by `getConfig().unstable_eventSystem` from `src/user-event/legacy/` or `src/user-event/modern/`, e.g. `findPressTarget()` for `press()` and `longPress()`. The modern one reuses modern `fireEvent`'s hit testing and responder negotiation (`getTouchPath()` and `findResponder()` in `src/events/modern/pressability.ts`), so both press the same element. It keeps the press on a `TextInput`, which claims the touch on a device even without `onPress*` props; the legacy one passes it on to the nearest ancestor that handles it.
+Where the two event systems need different rules, the action picks them by `getConfig().unstable_eventSystem` from `src/user-event/legacy/` or `src/user-event/modern/`, e.g. for `press()` and `longPress()`. Legacy `findPressTarget()` finds the element, then the action calls `onResponderGrant` and `onResponderRelease` of a touch responder, so Pressability runs with its timers, or the `onPress*` props of a host, with stub touch events. Modern `emitPressEvents()` reuses modern `fireEvent`'s hit testing and responder negotiation (`getTouchPath()` and `findResponder()` in `src/events/modern/pressability.ts`), so both press the same element. It keeps the press on a `TextInput`, which claims the touch on a device even without `onPress*` props; the legacy one passes it on to the nearest ancestor that handles it. It then calls the responder's Pressability callbacks itself, in Pressability's order, with `SyntheticEvent`s (`dispatchPressabilityEvent()`): `onPressIn`, `onLongPress` for `longPress()`, `onPressOut`, then `onPress` unless `onLongPress` was called. The action, not the touch duration, decides whether it is a long press, so neither action waits by default: `duration` only holds the touch, for timers in the component. Pressability's timing props (`delayLongPress`, `minPressDuration`, `delayPressIn`, `delayPressOut`) are ignored.
 
 For the `eventDiagnostics` warning, each action tracks itself with an `Interaction` from `src/user-event/utils/interaction.ts`:
 

src/events/__tests__/fire-event.test.tsx

@@ -39,17 +39,25 @@ const horizontalScrollEvent = { nativeEvent: { contentOffset: { x: 50 } } };
 const pressEventData = { nativeEvent: { pageX: 20, pageY: 30 } };
 const anySyntheticEvent = expect.any(SyntheticEvent);
 
-const defaultTouchPayload = {
-  changedTouches: [],
+const defaultTouch = {
   identifier: 0,
   locationX: 0,
   locationY: 0,
   pageX: 0,
   pageY: 0,
   target: 0,
   timestamp: expect.any(Number),
-  touches: [],
 };
+const defaultTouchPayload = { ...defaultTouch, changedTouches: [], touches: [] };
+
+/**
+ * Modern touch payload, as on a device: `changedTouches` has the touch, and so does `touches` until
+ * the touch ends.
+ */
+function getTouchPayload(isTouchStart: boolean, touchProps?: object) {
+  const touch = { ...defaultTouch, ...touchProps };
+  return { ...touch, changedTouches: [touch], touches: isTouchStart ? [touch] : [] };
+}
 
 beforeEach(() => {
   jest.spyOn(Date, 'now').mockImplementation(() => 100100100100);
@@ -301,10 +309,10 @@ describe('event object', () => {
   );
 
   test.each([
-    [{ target: 1 }, '"target". "target" is set by the dispatch.'],
+    [{ target: 1 }, '"target". "target" is provided by the event.'],
     [
       { target: {}, currentTarget: { measure: () => {} } },
-      '"target", "currentTarget". "target", "currentTarget" are set by the dispatch.',
+      '"target", "currentTarget". "target", "currentTarget" are provided by the event.',
     ],
     [{ persist: () => {} }, '"persist". "persist" is provided by the event.'],
     [
@@ -314,7 +322,7 @@ describe('event object', () => {
     [{ text: 'Hello' }, '"text". Pass "text" in "nativeEvent" instead.'],
     [
       { text: 'Hello', target: 1, persist: () => {} },
-      '"text", "target", "persist". "target" is set by the dispatch. "persist" is provided by the event. Pass "text" in "nativeEvent" instead.',
+      '"text", "target", "persist". "target", "persist" are provided by the event. Pass "text" in "nativeEvent" instead.',
     ],
   ])(
     'throws on unsupported keys %p (legacy: passes them to the handler)',
@@ -426,19 +434,10 @@ describe('fireEvent.press', () => {
     const onPress = jest.fn();
     await render(<Pressable testID="btn" onPress={onPress} />);
     await fireEvent.press(screen.getByTestId('btn'));
-    expect(onPress.mock.calls[0][0].nativeEvent).toMatchInlineSnapshot(`
-      {
-        "changedTouches": [],
-        "identifier": 0,
-        "locationX": 0,
-        "locationY": 0,
-        "pageX": 0,
-        "pageY": 0,
-        "target": 0,
-        "timestamp": 100100100100,
-        "touches": [],
-      }
-    `);
+    // Modern matches React Native, which fills the touch arrays. Legacy leaves them empty.
+    expect(onPress.mock.calls[0][0].nativeEvent).toEqual(
+      isModern() ? getTouchPayload(false) : { ...defaultTouchPayload, timestamp: 100100100100 },
+    );
     // Modern matches React Native, which passes a `SyntheticEvent`. Legacy passes a plain object
     // with stubs of its methods.
     expect(onPress.mock.calls[0][0] instanceof SyntheticEvent).toBe(isModern());
@@ -480,14 +479,20 @@ describe('fireEvent.press', () => {
 
     await fireEvent.press(screen.getByText('Press me'));
 
-    expect(event?.nativeEvent).toEqual(defaultTouchPayload);
+    expect(event?.nativeEvent).toEqual(isModern() ? getTouchPayload(false) : defaultTouchPayload);
     // Modern matches React Native: the event targets the pressed element, and Pressability calls
     // `onPress` of the responder. Legacy passes stubs as `target` and `currentTarget`.
     if (!isModern()) return;
-    expect(event?.type).toBe('press');
+    expect(event?.type).toBe('responderRelease');
+    expect(event?.dispatchConfig).toEqual({
+      registrationName: 'onResponderRelease',
+      dependencies: ['topTouchCancel', 'topTouchEnd'],
+    });
     expect(event?.target).toBe(screen.getByText('Press me'));
     expect(currentTarget).toBe(screen.getByTestId('pressable'));
-    expect(eventPhase).toBe(event?.BUBBLING_PHASE);
+    // The responder system calls the handler directly, without an event dispatch.
+    expect(eventPhase).toBe(event?.NONE);
+    expect(event?.isTrusted).toBe(false);
     // Reset after the dispatch.
     expect(event?.currentTarget).toBeNull();
   });
@@ -497,19 +502,11 @@ describe('fireEvent.press', () => {
     await render(<Pressable testID="btn" onPress={onPress} />);
     const customEventData = { nativeEvent: { pageX: 20, pageY: 30 }, timeStamp: 123 };
     await fireEvent.press(screen.getByTestId('btn'), customEventData);
-    expect(onPress.mock.calls[0][0].nativeEvent).toMatchInlineSnapshot(`
-      {
-        "changedTouches": [],
-        "identifier": 0,
-        "locationX": 0,
-        "locationY": 0,
-        "pageX": 20,
-        "pageY": 30,
-        "target": 0,
-        "timestamp": 100100100100,
-        "touches": [],
-      }
-    `);
+    expect(onPress.mock.calls[0][0].nativeEvent).toEqual(
+      isModern()
+        ? getTouchPayload(false, { pageX: 20, pageY: 30 })
+        : { ...defaultTouchPayload, pageX: 20, pageY: 30, timestamp: 100100100100 },
+    );
     expect(onPress.mock.calls[0][0].timeStamp).toBe(123);
     // Legacy merges the passed props into a plain event object.
     if (isModern()) return;
@@ -1644,7 +1641,6 @@ describe('direct events', () => {
     ),
   ];
 
-  // Builds one case per event type, passing the matching `on*` handler prop to `ui`.
   function buildDirectEventCases(
     source: string,
     eventTypes: string[],
@@ -1665,8 +1661,7 @@ describe('direct events', () => {
 
       await fireEvent(screen.getByTestId('target'), eventType, emptyEvent);
 
-      // Modern matches React Native: direct events don't bubble. Legacy still bubbles them, with a
-      // warning.
+      // Modern matches React Native: direct events don't bubble.
       expect(handler).toHaveBeenCalledTimes(isModern() ? 0 : 1);
       expect(warnSpy).toHaveBeenCalledTimes(isModern() ? 0 : 1);
     },
@@ -1712,8 +1707,7 @@ describe('direct events', () => {
 
     await fireEvent(screen.getByTestId('child'), 'onMomentumScrollEnd', emptyEvent);
 
-    // Modern matches React Native: direct events don't bubble. Legacy still bubbles them, with a
-    // warning.
+    // Modern matches React Native: direct events don't bubble.
     expect(onMomentumScrollEnd).toHaveBeenCalledTimes(isModern() ? 0 : 1);
     expect(warnSpy).toHaveBeenCalledTimes(isModern() ? 0 : 1);
   });
@@ -1728,8 +1722,7 @@ describe('direct events', () => {
 
     await fireEvent.scroll(screen.getByTestId('child'));
 
-    // Modern matches React Native: direct events don't bubble. Legacy still bubbles them, with a
-    // warning.
+    // Modern matches React Native: direct events don't bubble.
     expect(onScroll).toHaveBeenCalledTimes(isModern() ? 0 : 1);
     expect(warnSpy).toHaveBeenCalledTimes(isModern() ? 0 : 1);
     if (isModern()) return;
@@ -1775,7 +1768,6 @@ describe('direct events', () => {
     await fireEvent.scroll(screen.getByTestId('child'));
 
     // Modern matches React Native: scroll doesn't bubble, and composite props are never called.
-    // Legacy calls the composite prop, with a warning.
     expect(onScroll).toHaveBeenCalledTimes(isModern() ? 0 : 1);
     expect(warnSpy).toHaveBeenCalledTimes(isModern() ? 0 : 1);
   });
@@ -1890,7 +1882,7 @@ describe('Pressability event types', () => {
     expect(calls).toEqual([`pressable.${name}`, `touchable.${name}`]);
   });
 
-  test('passes a direct event with default touch payload (legacy: passes the event object as given)', async () => {
+  test('passes a responder event with default touch payload (legacy: passes the event object as given)', async () => {
     const onPressIn = jest.fn();
     await render(
       <Pressable testID="pressable" onPressIn={onPressIn}>
@@ -1906,15 +1898,39 @@ describe('Pressability event types', () => {
     const event = onPressIn.mock.calls[0][0];
     // Modern matches React Native, which derives Pressability events from a touch.
     expect(event.nativeEvent).toEqual(
-      isModern() ? { ...defaultTouchPayload, pageX: 20 } : { pageX: 20 },
+      isModern() ? getTouchPayload(true, { pageX: 20 }) : { pageX: 20 },
     );
     expect(event.timeStamp).toBe(123);
     if (!isModern()) return;
-    expect(event.type).toBe('pressin');
+    expect(event.type).toBe('responderGrant');
+    expect(event.dispatchConfig).toEqual({
+      registrationName: 'onResponderGrant',
+      dependencies: [],
+    });
+    // Not a direct event: the responder system calls the handler without an event dispatch.
     expect(event.bubbles).toBe(false);
-    expect(event.rnIsDirect).toBe(true);
+    expect(event.rnIsDirect).toBe(false);
     expect(event.target).toBe(screen.getByText('Press me'));
   });
+
+  test('calls onLongPress without currentTarget (legacy: passes the event object as given)', async () => {
+    let currentTarget: unknown;
+    await render(
+      <Pressable
+        onLongPress={(event) => {
+          currentTarget = event.currentTarget;
+        }}
+      >
+        <Text>Press me</Text>
+      </Pressable>,
+    );
+
+    await fireEvent(screen.getByText('Press me'), 'longPress', emptyEvent);
+
+    // Modern matches React Native, where Pressability calls `onLongPress` from a timer, after the
+    // dispatch of the responder grant event.
+    expect(currentTarget).toBe(isModern() ? null : undefined);
+  });
 });
 
 test('fireEvent throws for custom event (onCustomEvent) on composite component (legacy: calls it)', async () => {

src/events/dispatch-event.ts

@@ -1,29 +1,29 @@
 import type { TestInstance } from 'test-renderer';
 
 import type { LegacyEvent } from './create-event';
-import { dispatchEvent as dispatchLegacyEvent } from './legacy/dispatch';
 import { dispatchEvent as dispatchModernEvent } from './modern/dispatch';
 import { SyntheticEvent } from './modern/event';
+import { invokeEventHandler } from './shared/invoke-event-handler';
 
 /**
  * Dispatches an event from `createEvent()` to a host element. Used by `userEvent`.
  *
- * - Legacy event object: calls the element's own `on*` prop with it.
  * - `SyntheticEvent`: dispatched as React Native does (capture and bubble phases for bubbling
  *   events). `press` is a native event type (`topPress`), so it reaches host `onPress` props only,
  *   not `Pressable`'s `onPress`.
+ * - Legacy event object: calls the element's own `on*` prop with it.
  *
  * @param eventType a native event type without the `on*` prefix, e.g. `focus`
  * @returns `true` if a handler was called.
  */
 export async function dispatchEvent(
   instance: TestInstance,
   eventType: string,
-  event: LegacyEvent | SyntheticEvent,
+  event: SyntheticEvent | LegacyEvent,
 ): Promise<boolean> {
   if (event instanceof SyntheticEvent) {
     return await dispatchModernEvent(instance, event);
   }
 
-  return await dispatchLegacyEvent(instance, eventType, event);
+  return await invokeEventHandler(instance, eventType, event);
 }

src/events/legacy/__tests__/dispatch.test.tsx

@@ -20,7 +20,6 @@ export function baseSyntheticEvent(): BaseEvent {
   };
 }
 
-/** Wraps a `nativeEvent` in a legacy event object with `baseSyntheticEvent()` stubs. */
 export function wrapNativeEvent<T extends object>(nativeEvent: T) {
   return { ...baseSyntheticEvent(), nativeEvent };
 }