Add startGestureTransition API (#32785)

Stacked on #32783. This will replace [the `useSwipeTransition`
API](#32373).

Instead, of a special Hook, you can make updates to `useOptimistic`
Hooks within the `startGestureTransition` scope.

```
import {unstable_startGestureTransition as startGestureTransition} from 'react';

const cancel = startGestureTransition(timeline, () => {
  setOptimistic(...);
}, options);
```

There are some downsides to this like you can't define two directions as
once and there's no "standard" direction protocol. It's instead up to
libraries to come up with their own conventions (although we can suggest
some).

The convention is still that a gesture recognizer has two props `action`
and `gesture`. The `gesture` prop is a Gesture concept which now behaves
more like an Action but 1) it can't be async 2) it shouldn't have
side-effects. For example you can't call `setState()` in it except on
`useOptimistic` since those can be reverted if needed. The `action` is
invoked with whatever side-effects you want after the gesture fulfills.

This is isomorphic and not associated with a specific renderer nor root
so it's a bit more complicated.

To implement this I unify with the `ReactSharedInternal.T` property to
contain a regular Transition or a Gesture Transition (the `gesture`
field). The benefit of this unification means that every time we
override this based on some scope like entering `flushSync` we also
override the `startGestureTransition` scope. We just have to be careful
when we read it to check the `gesture` field to know which one it is.
(E.g. I error for setState / requestFormReset.)

The other thing that's unique is the `cancel` return value to know when
to stop the gesture. That cancellation is no longer associated with any
particular Hook. It's more associated with the scope of the
`startGestureTransition`. Since the schedule of whether a particular
gesture has rendered or committed is associated with a root, we need to
somehow associate any scheduled gestures with a root.

We could track which roots we update inside the scope but instead, I
went with a model where I check all the roots and see if there's a
scheduled gesture matching the timeline. This means that you could
"retain" a gesture across roots. Meaning this wouldn't cancel until both
are cancelled:

```
const cancelA = startGestureTransition(timeline, () => {
  setOptimisticOnRootA(...);
}, options);

const cancelB = startGestureTransition(timeline, () => {
  setOptimisticOnRootB(...);
}, options);
```

It's more like it's a global transition than associated with the roots
that were updated.

Optimistic updates mostly just work but I now associate them with a
specific "ScheduledGesture" instance since we can only render one at a
time and so if it's not the current one, we leave it for later.

Clean up of optimistic updates is now lazy rather than when we cancel.
Allowing the cancel closure not to have to be associated with each
particular update.

Author: sebmarkbage

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

@@ -1,13 +1,14 @@
 import React, {
   unstable_ViewTransition as ViewTransition,
   unstable_Activity as Activity,
-  unstable_useSwipeTransition as useSwipeTransition,
   useLayoutEffect,
   useEffect,
   useState,
   useId,
+  useOptimistic,
   startTransition,
 } from 'react';
+
 import {createPortal} from 'react-dom';
 
 import SwipeRecognizer from './SwipeRecognizer';
@@ -49,7 +50,12 @@ function Id() {
 }
 
 export default function Page({url, navigate}) {
-  const [renderedUrl, startGesture] = useSwipeTransition('/?a', url, '/?b');
+  const [renderedUrl, optimisticNavigate] = useOptimistic(
+    url,
+    (state, direction) => {
+      return direction === 'left' ? '/?a' : '/?b';
+    }
+  );
   const show = renderedUrl === '/?b';
   function onTransition(viewTransition, types) {
     const keyframes = [
@@ -107,7 +113,7 @@ export default function Page({url, navigate}) {
     <div className="swipe-recognizer">
       <SwipeRecognizer
         action={swipeAction}
-        gesture={startGesture}
+        gesture={optimisticNavigate}
         direction={show ? 'left' : 'right'}>
         <button
           className="button"

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

@@ -1,4 +1,9 @@
-import React, {useRef, useEffect, startTransition} from 'react';
+import React, {
+  useRef,
+  useEffect,
+  startTransition,
+  unstable_startGestureTransition as startGestureTransition,
+} from 'react';
 
 // Example of a Component that can recognize swipe gestures using a ScrollTimeline
 // without scrolling its own content. Allowing it to be used as an inert gesture
@@ -28,9 +33,15 @@ export default function SwipeRecognizer({
       source: scrollRef.current,
       axis: axis,
     });
-    activeGesture.current = gesture(scrollTimeline, {
-      range: [0, direction === 'left' || direction === 'up' ? 100 : 0, 100],
-    });
+    activeGesture.current = startGestureTransition(
+      scrollTimeline,
+      () => {
+        gesture(direction);
+      },
+      {
+        range: [0, direction === 'left' || direction === 'up' ? 100 : 0, 100],
+      }
+    );
   }
   function onScrollEnd() {
     let changed;

packages/react-reconciler/src/ReactFiberGestureScheduler.js

@@ -8,6 +8,7 @@
  */
 
 import type {FiberRoot} from './ReactInternalTypes';
+import type {GestureOptions} from 'shared/ReactTypes';
 import type {GestureTimeline, RunningViewTransition} from './ReactFiberConfig';
 
 import {
@@ -18,6 +19,7 @@ import {
 import {ensureRootIsScheduled} from './ReactFiberRootScheduler';
 import {
   subscribeToGestureDirection,
+  getCurrentGestureOffset,
   stopViewTransition,
 } from './ReactFiberConfig';
 
@@ -29,13 +31,14 @@ export type ScheduledGesture = {
   rangePrevious: number, // The end along the timeline where the previous state is reached.
   rangeCurrent: number, // The starting offset along the timeline.
   rangeNext: number, // The end along the timeline where the next state is reached.
-  cancel: () => void, // Cancel the subscription to direction change.
+  cancel: () => void, // Cancel the subscription to direction change. // TODO: Delete this.
   running: null | RunningViewTransition, // Used to cancel the running transition after we're done.
   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(
+// TODO: Delete this when deleting useSwipeTransition.
+export function scheduleGestureLegacy(
   root: FiberRoot,
   provider: GestureTimeline,
   initialDirection: boolean,
@@ -107,6 +110,100 @@ export function scheduleGesture(
   return gesture;
 }
 
+export function scheduleGesture(
+  root: FiberRoot,
+  provider: GestureTimeline,
+): ScheduledGesture {
+  let prev = root.pendingGestures;
+  while (prev !== null) {
+    if (prev.provider === provider) {
+      // Existing instance found.
+      return prev;
+    }
+    const next = prev.next;
+    if (next === null) {
+      break;
+    }
+    prev = next;
+  }
+  const gesture: ScheduledGesture = {
+    provider: provider,
+    count: 0,
+    direction: false,
+    rangePrevious: -1,
+    rangeCurrent: -1,
+    rangeNext: -1,
+    cancel: () => {}, // TODO: Delete this with useSwipeTransition.
+    running: null,
+    prev: prev,
+    next: null,
+  };
+  if (prev === null) {
+    root.pendingGestures = gesture;
+  } else {
+    prev.next = gesture;
+  }
+  ensureRootIsScheduled(root);
+  return gesture;
+}
+
+export function startScheduledGesture(
+  root: FiberRoot,
+  gestureTimeline: GestureTimeline,
+  gestureOptions: ?GestureOptions,
+): null | ScheduledGesture {
+  const currentOffset = getCurrentGestureOffset(gestureTimeline);
+  const range = gestureOptions && gestureOptions.range;
+  const rangePrevious: number = range ? range[0] : 0; // If no range is provider we assume it's the starting point of the range.
+  const rangeCurrent: number = range ? range[1] : currentOffset;
+  const rangeNext: number = range ? range[2] : 100; // If no range is provider we assume it's the starting point of the range.
+  if (__DEV__) {
+    if (
+      (rangePrevious > rangeCurrent && rangeNext > rangeCurrent) ||
+      (rangePrevious < rangeCurrent && rangeNext < rangeCurrent)
+    ) {
+      console.error(
+        'The range of a gesture needs "previous" and "next" to be on either side of ' +
+          'the "current" offset. Both cannot be above current and both cannot be below current.',
+      );
+    }
+  }
+  const isFlippedDirection = rangePrevious > rangeNext;
+  const initialDirection =
+    // If a range is specified we can imply initial direction if it's not the current
+    // value such as if the gesture starts after it has already moved.
+    currentOffset < rangeCurrent
+      ? isFlippedDirection
+      : currentOffset > rangeCurrent
+        ? !isFlippedDirection
+        : // Otherwise, look for an explicit option.
+          gestureOptions
+          ? gestureOptions.direction === 'next'
+          : false;
+
+  let prev = root.pendingGestures;
+  while (prev !== null) {
+    if (prev.provider === gestureTimeline) {
+      // Existing instance found.
+      prev.count++;
+      // Update the options.
+      prev.direction = initialDirection;
+      prev.rangePrevious = rangePrevious;
+      prev.rangeCurrent = rangeCurrent;
+      prev.rangeNext = rangeNext;
+      return prev;
+    }
+    const next = prev.next;
+    if (next === null) {
+      break;
+    }
+    prev = next;
+  }
+  // No scheduled gestures. It must mean nothing for this renderer updated but
+  // some other renderer might have updated.
+  return null;
+}
+
 export function cancelScheduledGesture(
   root: FiberRoot,
   gesture: ScheduledGesture,