Polyfill onScrollEnd Event in Safari (facebook#32427)

We added support for `onScrollEnd` in facebook#26789 but it only works in Chrome
and Firefox. Safari still doesn't support `scrollend` and there's no
indication that they will anytime soon so this polyfills it.

While I don't particularly love our synthetic event system this tries to
stay within the realm of how our other polyfills work. This implements
all `onScrollEnd` events as a plugin.

The basic principle is to first feature detect the `onscrollend` DOM
property to see if there's native support and otherwise just use the
native event.

Then we listen to `scroll` events and set a timeout. If we don't get any
more scroll events before the timeout we fire `onScrollEnd`. Basically
debouncing it. If we're currently pressing down on touch or a mouse then
we wait until it is lifted such as if you're scrolling with a finger or
using the scrollbars on desktop but isn't currently moving.

If we do get any native events even though we're in polyfilling mode, we
use that as an indication to fire the `onScrollEnd` early.

Part of the motivation is that this becomes extra useful pair for
facebook#32422. We also probably need
these events to coincide with other gesture related internals so you're
better off using our polyfill so they're synced.

Author: sebmarkbage

packages/react-dom-bindings/src/client/ReactDOMComponent.js

@@ -65,7 +65,10 @@ import sanitizeURL from '../shared/sanitizeURL';
 
 import {trackHostMutation} from 'react-reconciler/src/ReactFiberMutationTracking';
 
-import {enableTrustedTypesIntegration} from 'shared/ReactFeatureFlags';
+import {
+  enableScrollEndPolyfill,
+  enableTrustedTypesIntegration,
+} from 'shared/ReactFeatureFlags';
 import {
   mediaEventTypes,
   listenToNonDelegatedEvent,
@@ -545,6 +548,10 @@ function setProp(
           warnForInvalidEventListener(key, value);
         }
         listenToNonDelegatedEvent('scrollend', domElement);
+        if (enableScrollEndPolyfill) {
+          // For use by the polyfill.
+          listenToNonDelegatedEvent('scroll', domElement);
+        }
       }
       return;
     }
@@ -955,6 +962,10 @@ function setPropOnCustomElement(
           warnForInvalidEventListener(key, value);
         }
         listenToNonDelegatedEvent('scrollend', domElement);
+        if (enableScrollEndPolyfill) {
+          // For use by the polyfill.
+          listenToNonDelegatedEvent('scroll', domElement);
+        }
       }
       return;
     }
@@ -3058,6 +3069,10 @@ export function hydrateProperties(
 
   if (props.onScrollEnd != null) {
     listenToNonDelegatedEvent('scrollend', domElement);
+    if (enableScrollEndPolyfill) {
+      // For use by the polyfill.
+      listenToNonDelegatedEvent('scroll', domElement);
+    }
   }
 
   if (props.onClick != null) {

packages/react-dom-bindings/src/client/ReactDOMComponentTree.js

@@ -45,6 +45,7 @@ const internalEventHandlerListenersKey = '__reactListeners$' + randomKey;
 const internalEventHandlesSetKey = '__reactHandles$' + randomKey;
 const internalRootNodeResourcesKey = '__reactResources$' + randomKey;
 const internalHoistableMarker = '__reactMarker$' + randomKey;
+const internalScrollTimer = '__reactScroll$' + randomKey;
 
 export function detachDeletedInstance(node: Instance): void {
   // TODO: This function is only called on host components. I don't think all of
@@ -293,6 +294,18 @@ export function markNodeAsHoistable(node: Node) {
   (node: any)[internalHoistableMarker] = true;
 }
 
+export function getScrollEndTimer(node: EventTarget): ?TimeoutID {
+  return (node: any)[internalScrollTimer];
+}
+
+export function setScrollEndTimer(node: EventTarget, timer: TimeoutID): void {
+  (node: any)[internalScrollTimer] = timer;
+}
+
+export function clearScrollEndTimer(node: EventTarget): void {
+  (node: any)[internalScrollTimer] = undefined;
+}
+
 export function isOwnedInstance(node: Node): boolean {
   return !!(
     (node: any)[internalHoistableMarker] || (node: any)[internalInstanceKey]

packages/react-dom-bindings/src/events/DOMEventProperties.js

@@ -20,7 +20,10 @@ import {
   TRANSITION_END,
 } from './DOMEventNames';
 
-import {enableCreateEventHandleAPI} from 'shared/ReactFeatureFlags';
+import {
+  enableCreateEventHandleAPI,
+  enableScrollEndPolyfill,
+} from 'shared/ReactFeatureFlags';
 
 export const topLevelEventsToReactNames: Map<DOMEventName, string | null> =
   new Map();
@@ -100,13 +103,16 @@ const simpleEventPluginEvents = [
   'touchStart',
   'volumeChange',
   'scroll',
-  'scrollEnd',
   'toggle',
   'touchMove',
   'waiting',
   'wheel',
 ];
 
+if (!enableScrollEndPolyfill) {
+  simpleEventPluginEvents.push('scrollEnd');
+}
+
 if (enableCreateEventHandleAPI) {
   // Special case: these two events don't have on* React handler
   // and are only accessible via the createEventHandle API.

packages/react-dom-bindings/src/events/DOMPluginEventSystem.js

@@ -54,6 +54,7 @@ import {
   enableScopeAPI,
   enableOwnerStacks,
   disableCommentsAsDOMContainers,
+  enableScrollEndPolyfill,
 } from 'shared/ReactFeatureFlags';
 import {createEventListenerWrapperWithPriority} from './ReactDOMEventListener';
 import {
@@ -69,6 +70,7 @@ import * as EnterLeaveEventPlugin from './plugins/EnterLeaveEventPlugin';
 import * as SelectEventPlugin from './plugins/SelectEventPlugin';
 import * as SimpleEventPlugin from './plugins/SimpleEventPlugin';
 import * as FormActionEventPlugin from './plugins/FormActionEventPlugin';
+import * as ScrollEndEventPlugin from './plugins/ScrollEndEventPlugin';
 
 import reportGlobalError from 'shared/reportGlobalError';
 
@@ -93,6 +95,9 @@ EnterLeaveEventPlugin.registerEvents();
 ChangeEventPlugin.registerEvents();
 SelectEventPlugin.registerEvents();
 BeforeInputEventPlugin.registerEvents();
+if (enableScrollEndPolyfill) {
+  ScrollEndEventPlugin.registerEvents();
+}
 
 function extractEvents(
   dispatchQueue: DispatchQueue,
@@ -184,6 +189,17 @@ function extractEvents(
       targetContainer,
     );
   }
+  if (enableScrollEndPolyfill) {
+    ScrollEndEventPlugin.extractEvents(
+      dispatchQueue,
+      domEventName,
+      targetInst,
+      nativeEvent,
+      nativeEventTarget,
+      eventSystemFlags,
+      targetContainer,
+    );
+  }
 }
 
 // List of events that need to be individually attached to media elements.
@@ -811,6 +827,7 @@ export function accumulateSinglePhaseListeners(
 // - BeforeInputEventPlugin
 // - ChangeEventPlugin
 // - SelectEventPlugin
+// - ScrollEndEventPlugin
 // This is because we only process these plugins
 // in the bubble phase, so we need to accumulate two
 // phase event listeners (via emulation).
@@ -846,9 +863,14 @@ export function accumulateTwoPhaseListeners(
         );
       }
     }
+    if (instance.tag === HostRoot) {
+      return listeners;
+    }
     instance = instance.return;
   }
-  return listeners;
+  // If we didn't reach the root it means we're unmounted and shouldn't
+  // dispatch any events on the target.
+  return [];
 }
 
 function getParent(inst: Fiber | null): Fiber | null {

packages/react-dom-bindings/src/events/plugins/ScrollEndEventPlugin.js

@@ -0,0 +1,212 @@
+/**
+ * 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
+ */
+import type {AnyNativeEvent} from '../PluginModuleType';
+import type {DOMEventName} from '../DOMEventNames';
+import type {DispatchQueue} from '../DOMPluginEventSystem';
+import type {EventSystemFlags} from '../EventSystemFlags';
+import type {Fiber} from 'react-reconciler/src/ReactInternalTypes';
+import type {ReactSyntheticEvent} from '../ReactSyntheticEventType';
+
+import {registerTwoPhaseEvent} from '../EventRegistry';
+import {SyntheticUIEvent} from '../SyntheticEvent';
+
+import {canUseDOM} from 'shared/ExecutionEnvironment';
+import isEventSupported from '../isEventSupported';
+
+import {IS_CAPTURE_PHASE} from '../EventSystemFlags';
+
+import {batchedUpdates} from '../ReactDOMUpdateBatching';
+import {
+  processDispatchQueue,
+  accumulateSinglePhaseListeners,
+  accumulateTwoPhaseListeners,
+} from '../DOMPluginEventSystem';
+
+import {
+  getScrollEndTimer,
+  setScrollEndTimer,
+  clearScrollEndTimer,
+} from '../../client/ReactDOMComponentTree';
+
+import {enableScrollEndPolyfill} from 'shared/ReactFeatureFlags';
+
+const isScrollEndEventSupported =
+  enableScrollEndPolyfill && canUseDOM && isEventSupported('scrollend');
+
+let isTouchStarted = false;
+let isMouseDown = false;
+
+function registerEvents() {
+  registerTwoPhaseEvent('onScrollEnd', [
+    'scroll',
+    'scrollend',
+    'touchstart',
+    'touchcancel',
+    'touchend',
+    'mousedown',
+    'mouseup',
+  ]);
+}
+
+function manualDispatchScrollEndEvent(
+  inst: Fiber,
+  nativeEvent: AnyNativeEvent,
+  target: EventTarget,
+) {
+  const dispatchQueue: DispatchQueue = [];
+  const listeners = accumulateTwoPhaseListeners(inst, 'onScrollEnd');
+  if (listeners.length > 0) {
+    const event: ReactSyntheticEvent = new SyntheticUIEvent(
+      'onScrollEnd',
+      'scrollend',
+      null,
+      nativeEvent, // This will be the "scroll" event.
+      target,
+    );
+    dispatchQueue.push({event, listeners});
+  }
+  batchedUpdates(runEventInBatch, dispatchQueue);
+}
+
+function runEventInBatch(dispatchQueue: DispatchQueue) {
+  processDispatchQueue(dispatchQueue, 0);
+}
+
+function fireScrollEnd(
+  targetInst: Fiber,
+  nativeEvent: AnyNativeEvent,
+  nativeEventTarget: EventTarget,
+): void {
+  clearScrollEndTimer(nativeEventTarget);
+  if (isMouseDown || isTouchStarted) {
+    // If mouse or touch is down, try again later in case this is due to having an
+    // active scroll but it's not currently moving.
+    debounceScrollEnd(targetInst, nativeEvent, nativeEventTarget);
+    return;
+  }
+  manualDispatchScrollEndEvent(targetInst, nativeEvent, nativeEventTarget);
+}
+
+// When scrolling slows down the frequency of new scroll events can be quite low.
+// This timeout seems high enough to cover those cases but short enough to not
+// fire the event way too late.
+const DEBOUNCE_TIMEOUT = 200;
+
+function debounceScrollEnd(
+  targetInst: null | Fiber,
+  nativeEvent: AnyNativeEvent,
+  nativeEventTarget: EventTarget,
+) {
+  const existingTimer = getScrollEndTimer(nativeEventTarget);
+  if (existingTimer != null) {
+    clearTimeout(existingTimer);
+  }
+  if (targetInst !== null) {
+    const newTimer = setTimeout(
+      fireScrollEnd.bind(null, targetInst, nativeEvent, nativeEventTarget),
+      DEBOUNCE_TIMEOUT,
+    );
+    setScrollEndTimer(nativeEventTarget, newTimer);
+  }
+}
+
+/**
+ * This plugin creates an `onScrollEnd` event polyfill when the native one
+ * is not available.
+ */
+function extractEvents(
+  dispatchQueue: DispatchQueue,
+  domEventName: DOMEventName,
+  targetInst: null | Fiber,
+  nativeEvent: AnyNativeEvent,
+  nativeEventTarget: null | EventTarget,
+  eventSystemFlags: EventSystemFlags,
+  targetContainer: null | EventTarget,
+) {
+  if (!enableScrollEndPolyfill) {
+    return;
+  }
+
+  const inCapturePhase = (eventSystemFlags & IS_CAPTURE_PHASE) !== 0;
+
+  if (domEventName !== 'scrollend') {
+    if (!isScrollEndEventSupported && inCapturePhase) {
+      switch (domEventName) {
+        case 'scroll': {
+          if (nativeEventTarget !== null) {
+            debounceScrollEnd(targetInst, nativeEvent, nativeEventTarget);
+          }
+          break;
+        }
+        case 'touchstart': {
+          isTouchStarted = true;
+          break;
+        }
+        case 'touchcancel':
+        case 'touchend': {
+          // Note we cannot use pointer events for this because they get
+          // cancelled when native scrolling takes control.
+          isTouchStarted = false;
+          break;
+        }
+        case 'mousedown': {
+          isMouseDown = true;
+          break;
+        }
+        case 'mouseup': {
+          isMouseDown = false;
+          break;
+        }
+      }
+    }
+    return;
+  }
+
+  if (!isScrollEndEventSupported && nativeEventTarget !== null) {
+    const existingTimer = getScrollEndTimer(nativeEventTarget);
+    if (existingTimer != null) {
+      // If we do get a native scrollend event fired, we cancel the polyfill.
+      // This could happen if our feature detection is broken or if there's another
+      // polyfill calling dispatchEvent to fire it before we fire ours.
+      clearTimeout(existingTimer);
+      clearScrollEndTimer(nativeEventTarget);
+    } else {
+      // If we didn't receive a 'scroll' event first, we ignore this event to avoid
+      // double firing. Such as if we fired our onScrollEnd polyfill and then
+      // we also observed a native one afterwards.
+      return;
+    }
+  }
+
+  // In React onScrollEnd doesn't bubble.
+  const accumulateTargetOnly = !inCapturePhase;
+
+  const listeners = accumulateSinglePhaseListeners(
+    targetInst,
+    'onScrollEnd',
+    'scrollend',
+    inCapturePhase,
+    accumulateTargetOnly,
+    nativeEvent,
+  );
+
+  if (listeners.length > 0) {
+    // Intentionally create event lazily.
+    const event: ReactSyntheticEvent = new SyntheticUIEvent(
+      'onScrollEnd',
+      'scrollend',
+      null,
+      nativeEvent,
+      nativeEventTarget,
+    );
+    dispatchQueue.push({event, listeners});
+  }
+}
+
+export {registerEvents, extractEvents};

packages/shared/ReactFeatureFlags.js

@@ -94,6 +94,8 @@ export const enableViewTransition = __EXPERIMENTAL__;
 
 export const enableSwipeTransition = __EXPERIMENTAL__;
 
+export const enableScrollEndPolyfill = __EXPERIMENTAL__;
+
 /**
  * Switches the Fabric API from doing layout in commit work instead of complete work.
  */

packages/shared/forks/ReactFeatureFlags.native-fb.js

@@ -85,6 +85,7 @@ export const enableYieldingBeforePassive = false;
 export const enableThrottledScheduling = false;
 export const enableViewTransition = false;
 export const enableSwipeTransition = false;
+export const enableScrollEndPolyfill = true;
 
 // Flow magic to verify the exports of this file match the original version.
 ((((null: any): ExportsType): FeatureFlagsType): ExportsType);