Add optional initialValue argument to useDeferredValue (#27500)

Adds a second argument to useDeferredValue called initialValue:

```js
const value = useDeferredValue(finalValue, initialValue);
```

During the initial render of a component, useDeferredValue will return
initialValue. Once that render finishes, it will spawn an additional
render to switch to finalValue.

This same sequence should occur whenever the hook is hidden and revealed
again, i.e. by a Suspense or Activity, though this part is not yet
implemented.

When initialValue is not provided, useDeferredValue has no effect during
initial render, but during an update, it will remain on the previous
value, then spawn an additional render to switch to the new value. (This
is the same behavior that exists today.)

During SSR, initialValue is always used, if provided.

This feature is currently behind an experimental flag. We plan to ship
it in a non-breaking release.

DiffTrain build for [be67db4](be67db4)

Author: acdlite

compiled/facebook-www/REVISION

@@ -1 +1 @@
-151e75a128d0fd436dce365335b96c5686f704d4
+be67db46b60d94f9fbefccf2523429af25873e5b

compiled/facebook-www/React-dev.classic.js

@@ -27,7 +27,7 @@ if (
 }
           "use strict";
 
-var ReactVersion = "18.3.0-www-classic-f4ae0982";
+var ReactVersion = "18.3.0-www-classic-5bedd128";
 
 // ATTENTION
 // When adding new symbols to this file,
@@ -1986,9 +1986,9 @@ function useTransition() {
   var dispatcher = resolveDispatcher();
   return dispatcher.useTransition();
 }
-function useDeferredValue(value) {
+function useDeferredValue(value, initialValue) {
   var dispatcher = resolveDispatcher();
-  return dispatcher.useDeferredValue(value);
+  return dispatcher.useDeferredValue(value, initialValue);
 }
 function useId() {
   var dispatcher = resolveDispatcher();

compiled/facebook-www/React-dev.modern.js

@@ -27,7 +27,7 @@ if (
 }
           "use strict";
 
-var ReactVersion = "18.3.0-www-modern-06b61106";
+var ReactVersion = "18.3.0-www-modern-6dbff8b1";
 
 // ATTENTION
 // When adding new symbols to this file,
@@ -1986,9 +1986,9 @@ function useTransition() {
   var dispatcher = resolveDispatcher();
   return dispatcher.useTransition();
 }
-function useDeferredValue(value) {
+function useDeferredValue(value, initialValue) {
   var dispatcher = resolveDispatcher();
-  return dispatcher.useDeferredValue(value);
+  return dispatcher.useDeferredValue(value, initialValue);
 }
 function useId() {
   var dispatcher = resolveDispatcher();

compiled/facebook-www/React-prod.classic.js

@@ -576,8 +576,8 @@ exports.useContext = function (Context) {
   return ReactCurrentDispatcher.current.useContext(Context);
 };
 exports.useDebugValue = function () {};
-exports.useDeferredValue = function (value) {
-  return ReactCurrentDispatcher.current.useDeferredValue(value);
+exports.useDeferredValue = function (value, initialValue) {
+  return ReactCurrentDispatcher.current.useDeferredValue(value, initialValue);
 };
 exports.useEffect = function (create, deps) {
   return ReactCurrentDispatcher.current.useEffect(create, deps);
@@ -623,4 +623,4 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactCurrentDispatcher.current.useTransition();
 };
-exports.version = "18.3.0-www-classic-b08870f0";
+exports.version = "18.3.0-www-classic-20c4b7b9";

compiled/facebook-www/React-prod.modern.js

@@ -568,8 +568,8 @@ exports.useContext = function (Context) {
   return ReactCurrentDispatcher.current.useContext(Context);
 };
 exports.useDebugValue = function () {};
-exports.useDeferredValue = function (value) {
-  return ReactCurrentDispatcher.current.useDeferredValue(value);
+exports.useDeferredValue = function (value, initialValue) {
+  return ReactCurrentDispatcher.current.useDeferredValue(value, initialValue);
 };
 exports.useEffect = function (create, deps) {
   return ReactCurrentDispatcher.current.useEffect(create, deps);
@@ -615,4 +615,4 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactCurrentDispatcher.current.useTransition();
 };
-exports.version = "18.3.0-www-modern-20e3e48a";
+exports.version = "18.3.0-www-modern-1eaea04e";

compiled/facebook-www/React-profiling.classic.js

@@ -587,8 +587,8 @@ exports.useContext = function (Context) {
   return ReactCurrentDispatcher.current.useContext(Context);
 };
 exports.useDebugValue = function () {};
-exports.useDeferredValue = function (value) {
-  return ReactCurrentDispatcher.current.useDeferredValue(value);
+exports.useDeferredValue = function (value, initialValue) {
+  return ReactCurrentDispatcher.current.useDeferredValue(value, initialValue);
 };
 exports.useEffect = function (create, deps) {
   return ReactCurrentDispatcher.current.useEffect(create, deps);
@@ -634,7 +634,7 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactCurrentDispatcher.current.useTransition();
 };
-exports.version = "18.3.0-www-classic-fce6281b";
+exports.version = "18.3.0-www-classic-fcaf1567";
 
           /* global __REACT_DEVTOOLS_GLOBAL_HOOK__ */
 if (

compiled/facebook-www/React-profiling.modern.js

@@ -579,8 +579,8 @@ exports.useContext = function (Context) {
   return ReactCurrentDispatcher.current.useContext(Context);
 };
 exports.useDebugValue = function () {};
-exports.useDeferredValue = function (value) {
-  return ReactCurrentDispatcher.current.useDeferredValue(value);
+exports.useDeferredValue = function (value, initialValue) {
+  return ReactCurrentDispatcher.current.useDeferredValue(value, initialValue);
 };
 exports.useEffect = function (create, deps) {
   return ReactCurrentDispatcher.current.useEffect(create, deps);
@@ -626,7 +626,7 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactCurrentDispatcher.current.useTransition();
 };
-exports.version = "18.3.0-www-modern-b51738eb";
+exports.version = "18.3.0-www-modern-316f00ed";
 
           /* global __REACT_DEVTOOLS_GLOBAL_HOOK__ */
 if (

compiled/facebook-www/ReactART-dev.classic.js

@@ -69,7 +69,7 @@ function _assertThisInitialized(self) {
   return self;
 }
 
-var ReactVersion = "18.3.0-www-classic-01513ba4";
+var ReactVersion = "18.3.0-www-classic-839801a3";
 
 var LegacyRoot = 0;
 var ConcurrentRoot = 1;
@@ -180,7 +180,9 @@ var replayFailedUnitOfWorkWithInvokeGuardedCallback =
   enableDO_NOT_USE_disableStrictPassiveEffect =
     dynamicFeatureFlags.enableDO_NOT_USE_disableStrictPassiveEffect,
   disableSchedulerTimeoutInWorkLoop =
-    dynamicFeatureFlags.disableSchedulerTimeoutInWorkLoop; // On WWW, false is used for a new modern build.
+    dynamicFeatureFlags.disableSchedulerTimeoutInWorkLoop,
+  enableUseDeferredValueInitialArg =
+    dynamicFeatureFlags.enableUseDeferredValueInitialArg; // On WWW, false is used for a new modern build.
 var enableProfilerTimer = true;
 var enableProfilerCommitHooks = true;
 var enableProfilerNestedUpdatePhase = true;
@@ -9740,34 +9742,61 @@ function updateMemo(nextCreate, deps) {
   return nextValue;
 }
 
-function mountDeferredValue(value) {
+function mountDeferredValue(value, initialValue) {
   var hook = mountWorkInProgressHook();
-  hook.memoizedState = value;
-  return value;
+  return mountDeferredValueImpl(hook, value, initialValue);
 }
 
-function updateDeferredValue(value) {
+function updateDeferredValue(value, initialValue) {
   var hook = updateWorkInProgressHook();
   var resolvedCurrentHook = currentHook;
   var prevValue = resolvedCurrentHook.memoizedState;
   return updateDeferredValueImpl(hook, prevValue, value);
 }
 
-function rerenderDeferredValue(value) {
+function rerenderDeferredValue(value, initialValue) {
   var hook = updateWorkInProgressHook();
 
   if (currentHook === null) {
     // This is a rerender during a mount.
-    hook.memoizedState = value;
-    return value;
+    return mountDeferredValueImpl(hook, value, initialValue);
   } else {
     // This is a rerender during an update.
     var prevValue = currentHook.memoizedState;
     return updateDeferredValueImpl(hook, prevValue, value);
   }
 }
 
-function updateDeferredValueImpl(hook, prevValue, value) {
+function mountDeferredValueImpl(hook, value, initialValue) {
+  if (enableUseDeferredValueInitialArg && initialValue !== undefined) {
+    // When `initialValue` is provided, we defer the initial render even if the
+    // current render is not synchronous.
+    // TODO: However, to avoid waterfalls, we should not defer if this render
+    // was itself spawned by an earlier useDeferredValue. Plan is to add a
+    // Deferred lane to track this.
+    hook.memoizedState = initialValue; // Schedule a deferred render
+
+    var deferredLane = claimNextTransitionLane();
+    currentlyRenderingFiber$1.lanes = mergeLanes(
+      currentlyRenderingFiber$1.lanes,
+      deferredLane
+    );
+    markSkippedUpdateLanes(deferredLane); // Set this to true to indicate that the rendered value is inconsistent
+    // from the latest value. The name "baseState" doesn't really match how we
+    // use it because we're reusing a state hook field instead of creating a
+    // new one.
+
+    hook.baseState = true;
+    return initialValue;
+  } else {
+    hook.memoizedState = value;
+    return value;
+  }
+}
+
+function updateDeferredValueImpl(hook, prevValue, value, initialValue) {
+  // TODO: We should also check if this component is going from
+  // hidden -> visible. If so, it should use the initialValue arg.
   var shouldDeferValue = !includesOnlyNonUrgentLanes(renderLanes$1);
 
   if (shouldDeferValue) {
@@ -10463,10 +10492,10 @@ var InvalidNestedHooksDispatcherOnRerenderInDEV = null;
       mountHookTypesDev();
       return mountDebugValue();
     },
-    useDeferredValue: function (value) {
+    useDeferredValue: function (value, initialValue) {
       currentHookNameInDev = "useDeferredValue";
       mountHookTypesDev();
-      return mountDeferredValue(value);
+      return mountDeferredValue(value, initialValue);
     },
     useTransition: function () {
       currentHookNameInDev = "useTransition";
@@ -10602,10 +10631,10 @@ var InvalidNestedHooksDispatcherOnRerenderInDEV = null;
       updateHookTypesDev();
       return mountDebugValue();
     },
-    useDeferredValue: function (value) {
+    useDeferredValue: function (value, initialValue) {
       currentHookNameInDev = "useDeferredValue";
       updateHookTypesDev();
-      return mountDeferredValue(value);
+      return mountDeferredValue(value, initialValue);
     },
     useTransition: function () {
       currentHookNameInDev = "useTransition";
@@ -10739,7 +10768,7 @@ var InvalidNestedHooksDispatcherOnRerenderInDEV = null;
       updateHookTypesDev();
       return updateDebugValue();
     },
-    useDeferredValue: function (value) {
+    useDeferredValue: function (value, initialValue) {
       currentHookNameInDev = "useDeferredValue";
       updateHookTypesDev();
       return updateDeferredValue(value);
@@ -10878,10 +10907,10 @@ var InvalidNestedHooksDispatcherOnRerenderInDEV = null;
       updateHookTypesDev();
       return updateDebugValue();
     },
-    useDeferredValue: function (value) {
+    useDeferredValue: function (value, initialValue) {
       currentHookNameInDev = "useDeferredValue";
       updateHookTypesDev();
-      return rerenderDeferredValue(value);
+      return rerenderDeferredValue(value, initialValue);
     },
     useTransition: function () {
       currentHookNameInDev = "useTransition";
@@ -11033,11 +11062,11 @@ var InvalidNestedHooksDispatcherOnRerenderInDEV = null;
       mountHookTypesDev();
       return mountDebugValue();
     },
-    useDeferredValue: function (value) {
+    useDeferredValue: function (value, initialValue) {
       currentHookNameInDev = "useDeferredValue";
       warnInvalidHookAccess();
       mountHookTypesDev();
-      return mountDeferredValue(value);
+      return mountDeferredValue(value, initialValue);
     },
     useTransition: function () {
       currentHookNameInDev = "useTransition";
@@ -11194,7 +11223,7 @@ var InvalidNestedHooksDispatcherOnRerenderInDEV = null;
       updateHookTypesDev();
       return updateDebugValue();
     },
-    useDeferredValue: function (value) {
+    useDeferredValue: function (value, initialValue) {
       currentHookNameInDev = "useDeferredValue";
       warnInvalidHookAccess();
       updateHookTypesDev();
@@ -11355,11 +11384,11 @@ var InvalidNestedHooksDispatcherOnRerenderInDEV = null;
       updateHookTypesDev();
       return updateDebugValue();
     },
-    useDeferredValue: function (value) {
+    useDeferredValue: function (value, initialValue) {
       currentHookNameInDev = "useDeferredValue";
       warnInvalidHookAccess();
       updateHookTypesDev();
-      return rerenderDeferredValue(value);
+      return rerenderDeferredValue(value, initialValue);
     },
     useTransition: function () {
       currentHookNameInDev = "useTransition";