Add useSwipeTransition Hook Behind Experimental Flag (#32373)

This Hook will be used to drive a View Transition based on a gesture.

```js
const [value, startGesture] = useSwipeTransition(prev, current, next);
```

The `enableSwipeTransition` flag will depend on `enableViewTransition`
flag but we may decide to ship them independently. This PR doesn't do
anything interesting yet. There will be a lot more PRs to build out the
actual functionality. This is just wiring up the plumbing for the new
Hook.

This first PR is mainly concerned with how the whole starts (and stops).
The core API is the `startGesture` function (although there will be
other conveniences added in the future). You can call this to start a
gesture with a source provider. You can call this multiple times in one
event to batch multiple Hooks listening to the same provider. However,
each render can only handle one source provider at a time and so it does
one render per scheduled gesture provider.

This uses a separate `GestureLane` to drive gesture renders by marking
the Hook as having an update on that lane. Then schedule a render. These
renders should be blocking and in the same microtask as the
`startGesture` to ensure it can block the paint. So it's similar to
sync.

It may not be possible to finish it synchronously e.g. if something
suspends. If so, it just tries again later when it can like any other
render. This can also happen because it also may not be possible to
drive more than one gesture at a time like if we're limited to one View
Transition per document. So right now you can only run one gesture at a
time in practice.

These renders never commit. This means that we can't clear the
`GestureLane` the normal way. Instead, we have to clear only the root's
`pendingLanes` if we don't have any new renders scheduled. Then wait
until something else updates the Fiber after all gestures on it have
stopped before it really clears.

Author: sebmarkbage

fixtures/view-transition/src/components/Page.css

@@ -6,3 +6,14 @@
   font-variation-settings:
     "wdth" 100;
 }
+
+.swipe-recognizer {
+  width: 200px;
+  overflow-x: scroll;
+  border: 1px solid #333333;
+  border-radius: 10px;
+}
+
+.swipe-overscroll {
+  width: 200%;
+}

fixtures/view-transition/src/components/Page.js

@@ -1,6 +1,9 @@
 import React, {
   unstable_ViewTransition as ViewTransition,
   unstable_Activity as Activity,
+  unstable_useSwipeTransition as useSwipeTransition,
+  useRef,
+  useLayoutEffect,
 } from 'react';
 
 import './Page.css';
@@ -35,7 +38,8 @@ function Component() {
 }
 
 export default function Page({url, navigate}) {
-  const show = url === '/?b';
+  const [renderedUrl, startGesture] = useSwipeTransition('/?a', url, '/?b');
+  const show = renderedUrl === '/?b';
   function onTransition(viewTransition, types) {
     const keyframes = [
       {rotate: '0deg', transformOrigin: '30px 8px'},
@@ -44,6 +48,32 @@ export default function Page({url, navigate}) {
     viewTransition.old.animate(keyframes, 250);
     viewTransition.new.animate(keyframes, 250);
   }
+
+  const swipeRecognizer = useRef(null);
+  const activeGesture = useRef(null);
+  function onScroll() {
+    if (activeGesture.current !== null) {
+      return;
+    }
+    // eslint-disable-next-line no-undef
+    const scrollTimeline = new ScrollTimeline({
+      source: swipeRecognizer.current,
+      axis: 'x',
+    });
+    activeGesture.current = startGesture(scrollTimeline);
+  }
+  function onScrollEnd() {
+    if (activeGesture.current !== null) {
+      const cancelGesture = activeGesture.current;
+      activeGesture.current = null;
+      cancelGesture();
+    }
+  }
+
+  useLayoutEffect(() => {
+    swipeRecognizer.current.scrollLeft = show ? 0 : 10000;
+  }, [show]);
+
   const exclamation = (
     <ViewTransition name="exclamation" onShare={onTransition}>
       <span>!</span>
@@ -90,6 +120,13 @@ export default function Page({url, navigate}) {
           <p></p>
           <p></p>
           <p></p>
+          <div
+            className="swipe-recognizer"
+            onScroll={onScroll}
+            onScrollEnd={onScrollEnd}
+            ref={swipeRecognizer}>
+            <div className="swipe-overscroll">Swipe me</div>
+          </div>
           <p></p>
           <p></p>
           {show ? null : (

packages/react-debug-tools/src/ReactDebugHooks.js

@@ -14,6 +14,7 @@ import type {
   Usable,
   Thenable,
   ReactDebugInfo,
+  StartGesture,
 } from 'shared/ReactTypes';
 import type {
   ContextDependency,
@@ -131,6 +132,9 @@ function getPrimitiveStackCache(): Map<string, Array<any>> {
       if (typeof Dispatcher.useEffectEvent === 'function') {
         Dispatcher.useEffectEvent((args: empty) => {});
       }
+      if (typeof Dispatcher.useSwipeTransition === 'function') {
+        Dispatcher.useSwipeTransition(null, null, null);
+      }
     } finally {
       readHookLog = hookLog;
       hookLog = [];
@@ -752,31 +756,50 @@ function useEffectEvent<Args, F: (...Array<Args>) => mixed>(callback: F): F {
   return callback;
 }
 
+function useSwipeTransition<T>(
+  previous: T,
+  current: T,
+  next: T,
+): [T, StartGesture] {
+  nextHook();
+  hookLog.push({
+    displayName: null,
+    primitive: 'SwipeTransition',
+    stackError: new Error(),
+    value: current,
+    debugInfo: null,
+    dispatcherHookName: 'SwipeTransition',
+  });
+  return [current, () => () => {}];
+}
+
 const Dispatcher: DispatcherType = {
-  use,
   readContext,
-  useCacheRefresh,
+
+  use,
   useCallback,
   useContext,
   useEffect,
   useImperativeHandle,
-  useDebugValue,
   useLayoutEffect,
   useInsertionEffect,
   useMemo,
-  useMemoCache,
-  useOptimistic,
   useReducer,
   useRef,
   useState,
+  useDebugValue,
+  useDeferredValue,
   useTransition,
   useSyncExternalStore,
-  useDeferredValue,
   useId,
+  useHostTransitionStatus,
   useFormState,
   useActionState,
-  useHostTransitionStatus,
+  useOptimistic,
+  useMemoCache,
+  useCacheRefresh,
   useEffectEvent,
+  useSwipeTransition,
 };
 
 // create a proxy to throw a custom error

packages/react-reconciler/src/ReactFiberConcurrentUpdates.js

@@ -24,7 +24,14 @@ import {
   throwIfInfiniteUpdateLoopDetected,
   getWorkInProgressRoot,
 } from './ReactFiberWorkLoop';
-import {NoLane, NoLanes, mergeLanes, markHiddenUpdate} from './ReactFiberLane';
+import {
+  NoLane,
+  NoLanes,
+  mergeLanes,
+  markHiddenUpdate,
+  markRootUpdated,
+  GestureLane,
+} from './ReactFiberLane';
 import {NoFlags, Placement, Hydrating} from './ReactFiberFlags';
 import {HostRoot, OffscreenComponent} from './ReactWorkTags';
 import {OffscreenVisible} from './ReactFiberActivityComponent';
@@ -169,6 +176,25 @@ export function enqueueConcurrentRenderForLane(
   return getRootForUpdatedFiber(fiber);
 }
 
+export function enqueueGestureRender(fiber: Fiber): FiberRoot | null {
+  // We can't use the concurrent queuing for these so this is basically just a
+  // short cut for marking the lane on the parent path. It is possible for a
+  // gesture render to suspend and then in the gap get another gesture starting.
+  // However, marking the lane doesn't make much different in this case because
+  // it would have to call startGesture with the same exact provider as was
+  // already rendering. Because otherwise it has no effect on the Hook itself.
+  // TODO: We could potentially solve this case by popping a ScheduledGesture
+  // off the root's queue while we're rendering it so that it can't dedupe
+  // and so new startGesture with the same provider would create a new
+  // ScheduledGesture which goes into a separate render pass anyway.
+  // This is such an edge case it probably doesn't matter much.
+  const root = markUpdateLaneFromFiberToRoot(fiber, null, GestureLane);
+  if (root !== null) {
+    markRootUpdated(root, GestureLane);
+  }
+  return root;
+}
+
 // Calling this function outside this module should only be done for backwards
 // compatibility and should always be accompanied by a warning.
 export function unsafe_markUpdateLaneFromFiberToRoot(
@@ -189,7 +215,7 @@ function markUpdateLaneFromFiberToRoot(
   sourceFiber: Fiber,
   update: ConcurrentUpdate | null,
   lane: Lane,
-): void {
+): null | FiberRoot {
   // Update the source fiber's lanes
   sourceFiber.lanes = mergeLanes(sourceFiber.lanes, lane);
   let alternate = sourceFiber.alternate;
@@ -238,10 +264,14 @@ function markUpdateLaneFromFiberToRoot(
     parent = parent.return;
   }
 
-  if (isHidden && update !== null && node.tag === HostRoot) {
+  if (node.tag === HostRoot) {
     const root: FiberRoot = node.stateNode;
-    markHiddenUpdate(root, update, lane);
+    if (isHidden && update !== null) {
+      markHiddenUpdate(root, update, lane);
+    }
+    return root;
   }
+  return null;
 }
 
 function getRootForUpdatedFiber(sourceFiber: Fiber): FiberRoot | null {

packages/react-reconciler/src/ReactFiberGestureScheduler.js

@@ -0,0 +1,90 @@
+/**
+ * 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 {FiberRoot} from './ReactInternalTypes';
+import type {GestureProvider} from 'shared/ReactTypes';
+
+import {GestureLane} from './ReactFiberLane';
+import {ensureRootIsScheduled} from './ReactFiberRootScheduler';
+
+// This type keeps track of any scheduled or active gestures.
+export type ScheduledGesture = {
+  provider: GestureProvider,
+  count: number, // The number of times this same provider has been started.
+  prev: null | ScheduledGesture, // The previous scheduled gesture in the queue for this root.
+  next: null | ScheduledGesture, // The next scheduled gesture in the queue for this root.
+};
+
+export function scheduleGesture(
+  root: FiberRoot,
+  provider: GestureProvider,
+): ScheduledGesture {
+  let prev = root.gestures;
+  while (prev !== null) {
+    if (prev.provider === provider) {
+      // Existing instance found.
+      prev.count++;
+      return prev;
+    }
+    const next = prev.next;
+    if (next === null) {
+      break;
+    }
+    prev = next;
+  }
+  // Add new instance to the end of the queue.
+  const gesture: ScheduledGesture = {
+    provider: provider,
+    count: 1,
+    prev: prev,
+    next: null,
+  };
+  if (prev === null) {
+    root.gestures = gesture;
+  } else {
+    prev.next = gesture;
+  }
+  ensureRootIsScheduled(root);
+  return gesture;
+}
+
+export function cancelScheduledGesture(
+  root: FiberRoot,
+  gesture: ScheduledGesture,
+): void {
+  gesture.count--;
+  if (gesture.count === 0) {
+    // Delete the scheduled gesture from the queue.
+    deleteScheduledGesture(root, gesture);
+  }
+}
+
+export function deleteScheduledGesture(
+  root: FiberRoot,
+  gesture: ScheduledGesture,
+): void {
+  if (gesture.prev === null) {
+    if (root.gestures === gesture) {
+      root.gestures = gesture.next;
+      if (root.gestures === null) {
+        // Gestures don't clear their lanes while the gesture is still active but it
+        // might not be scheduled to do any more renders and so we shouldn't schedule
+        // any more gesture lane work until a new gesture is scheduled.
+        root.pendingLanes &= ~GestureLane;
+      }
+    }
+  } else {
+    gesture.prev.next = gesture.next;
+    if (gesture.next !== null) {
+      gesture.next.prev = gesture.prev;
+    }
+    gesture.prev = null;
+    gesture.next = null;
+  }
+}