Add initialValue option to useDeferredValue

Currently, useDeferredValue only works for updates. It will never during
the initial render because there's no previous value to reuse. This
means it can't be used to implement progressive enhancement.

This adds an optional initialValue argument to useDeferredValue. When
provided, the initial mount will use initialValue if it's during an
urgent render. Otherwise it will use the latest, canonical value.

During server rendering and hydration, it will always use the
initialValue instead of the canonical value, regardless of priority, to
avoid a hydration mismatch.

The name "initial value" isn't ideal because during a non-urgent client
render, it's disregarded entirely. It's more like a "lightweight" value
that will later be upgraded to a "heavier" one. Needs some bikeshedding.

When initialValue is omitted, the behavior is the same as today.

Author: acdlite

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

@@ -309,7 +309,7 @@ function useTransition(): [
   return [false, callback => {}];
 }
 
-function useDeferredValue<T>(value: T): T {
+function useDeferredValue<T>(value: T, initialValue?: T): T {
   // useDeferredValue() composes multiple hooks internally.
   // Advance the current hook index the same number of times
   // so that subsequent hooks have the right memoized state.

packages/react-dom/src/__tests__/ReactDOMFizzServer-test.js

@@ -19,6 +19,7 @@ let Suspense;
 let SuspenseList;
 let useSyncExternalStore;
 let useSyncExternalStoreWithSelector;
+let useDeferredValue;
 let PropTypes;
 let textCache;
 let window;
@@ -61,6 +62,7 @@ describe('ReactDOMFizzServer', () => {
     useSyncExternalStore = React.useSyncExternalStore;
     useSyncExternalStoreWithSelector = require('use-sync-external-store/with-selector')
       .useSyncExternalStoreWithSelector;
+    useDeferredValue = React.useDeferredValue;
 
     textCache = new Map();
 
@@ -3084,4 +3086,40 @@ describe('ReactDOMFizzServer', () => {
 
     expect(Scheduler).toFlushAndYield([]);
   });
+
+  // @gate experimental
+  it('useDeferredValue uses initialValue during hydration even if render is not urgent', async () => {
+    function Child() {
+      const value = useDeferredValue('Canonical', 'Initial');
+      Scheduler.unstable_yieldValue(value);
+      return value;
+    }
+
+    function App() {
+      // Because the child is wrapped in a Suspense boundary, it hydrates
+      // at a non-urgent priority.
+      return (
+        <Suspense fallback="Loading...">
+          <Child />
+        </Suspense>
+      );
+    }
+
+    await act(async () => {
+      const {pipe} = ReactDOMFizzServer.renderToPipeableStream(<App />);
+      pipe(writable);
+    });
+    expect(Scheduler).toHaveYielded(['Initial']);
+    // The server always renders the initial value, not the canonical one.
+    expect(getVisibleChildren(container)).toEqual('Initial');
+
+    // When hydrating, it should use the initial value even if the hydration
+    // is (per usual) not urgent, to avoid a hydration mismatch. Then it does
+    // a deferred client render to switch to the canonical value.
+    // TODO: The deferred render should not be higher than the hydration itself,
+    // but currently it's always a transition.
+    ReactDOMClient.hydrateRoot(container, <App />);
+    expect(Scheduler).toFlushAndYield(['Initial', 'Canonical']);
+    expect(getVisibleChildren(container)).toEqual('Canonical');
+  });
 });

packages/react-dom/src/__tests__/ReactDOMServerIntegrationHooks-test.js

@@ -28,6 +28,7 @@ let useImperativeHandle;
 let useInsertionEffect;
 let useLayoutEffect;
 let useDebugValue;
+let useDeferredValue;
 let forwardRef;
 let yieldedValues;
 let yieldValue;
@@ -52,6 +53,7 @@ function initModules() {
   useImperativeHandle = React.useImperativeHandle;
   useInsertionEffect = React.useInsertionEffect;
   useLayoutEffect = React.useLayoutEffect;
+  useDeferredValue = React.useDeferredValue;
   forwardRef = React.forwardRef;
 
   yieldedValues = [];
@@ -663,6 +665,32 @@ describe('ReactDOMServerHooks', () => {
     });
   });
 
+  describe('useDeferredValue', () => {
+    it('renders with initialValue, if provided', async () => {
+      function Counter() {
+        const value1 = useDeferredValue('Latest', 'Initial');
+        const value2 = useDeferredValue('Latest');
+        return (
+          <div>
+            <div>{value1}</div>
+            <div>{value2}</div>
+          </div>
+        );
+      }
+      const domNode = await serverRender(<Counter />, 1);
+      expect(domNode).toMatchInlineSnapshot(`
+        <div>
+          <div>
+            Initial
+          </div>
+          <div>
+            Latest
+          </div>
+        </div>
+      `);
+    });
+  });
+
   describe('useContext', () => {
     itThrowsWhenRendering(
       'if used inside a class component',

packages/react-dom/src/server/ReactPartialRendererHooks.js

@@ -496,9 +496,9 @@ function useSyncExternalStore<T>(
   return getServerSnapshot();
 }
 
-function useDeferredValue<T>(value: T): T {
+function useDeferredValue<T>(value: T, initialValue?: T): T {
   resolveCurrentlyRenderingComponent();
-  return value;
+  return initialValue !== undefined ? initialValue : value;
 }
 
 function useTransition(): [boolean, (callback: () => void) => void] {

packages/react-reconciler/src/ReactFiberHooks.new.js

@@ -1927,32 +1927,59 @@ function updateMemo<T>(
   return nextValue;
 }
 
-function mountDeferredValue<T>(value: T): T {
+function mountDeferredValue<T>(value: T, initialValue?: T): T {
   const hook = mountWorkInProgressHook();
-  hook.memoizedState = value;
-  return value;
+  return mountDeferredValueImpl(hook, value, initialValue);
 }
 
-function updateDeferredValue<T>(value: T): T {
+function updateDeferredValue<T>(value: T, initialValue?: T): T {
   const hook = updateWorkInProgressHook();
   const resolvedCurrentHook: Hook = (currentHook: any);
   const prevValue: T = resolvedCurrentHook.memoizedState;
   return updateDeferredValueImpl(hook, prevValue, value);
 }
 
-function rerenderDeferredValue<T>(value: T): T {
+function rerenderDeferredValue<T>(value: T, initialValue?: T): T {
   const 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.
     const prevValue: T = currentHook.memoizedState;
     return updateDeferredValueImpl(hook, prevValue, value);
   }
 }
 
+function mountDeferredValueImpl<T>(hook: Hook, value: T, initialValue?: T): T {
+  // During hydration, if an initial value is provided, we always use that one
+  // regardless of the render priority. This means you can use it for
+  // progressive enhancement. Otherwise, we only use the initial value if the
+  // render is urgent — same logic as during an update.
+  if (
+    (getIsHydrating() || !includesOnlyNonUrgentLanes(renderLanes)) &&
+    initialValue !== undefined &&
+    !is(value, initialValue)
+  ) {
+    // Spawn a deferred render
+    const deferredLane = claimNextTransitionLane();
+    currentlyRenderingFiber.lanes = mergeLanes(
+      currentlyRenderingFiber.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;
+    value = initialValue;
+  }
+  hook.memoizedState = value;
+  return value;
+}
+
 function updateDeferredValueImpl<T>(hook: Hook, prevValue: T, value: T): T {
   const shouldDeferValue = !includesOnlyNonUrgentLanes(renderLanes);
   if (shouldDeferValue) {
@@ -2664,10 +2691,10 @@ if (__DEV__) {
       mountHookTypesDev();
       return mountDebugValue(value, formatterFn);
     },
-    useDeferredValue<T>(value: T): T {
+    useDeferredValue<T>(value: T, initialValue?: T): T {
       currentHookNameInDev = 'useDeferredValue';
       mountHookTypesDev();
-      return mountDeferredValue(value);
+      return mountDeferredValue(value, initialValue);
     },
     useTransition(): [boolean, (() => void) => void] {
       currentHookNameInDev = 'useTransition';
@@ -2806,10 +2833,10 @@ if (__DEV__) {
       updateHookTypesDev();
       return mountDebugValue(value, formatterFn);
     },
-    useDeferredValue<T>(value: T): T {
+    useDeferredValue<T>(value: T, initialValue?: T): T {
       currentHookNameInDev = 'useDeferredValue';
       updateHookTypesDev();
-      return mountDeferredValue(value);
+      return mountDeferredValue(value, initialValue);
     },
     useTransition(): [boolean, (() => void) => void] {
       currentHookNameInDev = 'useTransition';
@@ -2948,10 +2975,10 @@ if (__DEV__) {
       updateHookTypesDev();
       return updateDebugValue(value, formatterFn);
     },
-    useDeferredValue<T>(value: T): T {
+    useDeferredValue<T>(value: T, initialValue?: T): T {
       currentHookNameInDev = 'useDeferredValue';
       updateHookTypesDev();
-      return updateDeferredValue(value);
+      return updateDeferredValue(value, initialValue);
     },
     useTransition(): [boolean, (() => void) => void] {
       currentHookNameInDev = 'useTransition';
@@ -3091,10 +3118,10 @@ if (__DEV__) {
       updateHookTypesDev();
       return updateDebugValue(value, formatterFn);
     },
-    useDeferredValue<T>(value: T): T {
+    useDeferredValue<T>(value: T, initialValue?: T): T {
       currentHookNameInDev = 'useDeferredValue';
       updateHookTypesDev();
-      return rerenderDeferredValue(value);
+      return rerenderDeferredValue(value, initialValue);
     },
     useTransition(): [boolean, (() => void) => void] {
       currentHookNameInDev = 'useTransition';
@@ -3245,11 +3272,11 @@ if (__DEV__) {
       mountHookTypesDev();
       return mountDebugValue(value, formatterFn);
     },
-    useDeferredValue<T>(value: T): T {
+    useDeferredValue<T>(value: T, initialValue?: T): T {
       currentHookNameInDev = 'useDeferredValue';
       warnInvalidHookAccess();
       mountHookTypesDev();
-      return mountDeferredValue(value);
+      return mountDeferredValue(value, initialValue);
     },
     useTransition(): [boolean, (() => void) => void] {
       currentHookNameInDev = 'useTransition';
@@ -3404,11 +3431,11 @@ if (__DEV__) {
       updateHookTypesDev();
       return updateDebugValue(value, formatterFn);
     },
-    useDeferredValue<T>(value: T): T {
+    useDeferredValue<T>(value: T, initialValue?: T): T {
       currentHookNameInDev = 'useDeferredValue';
       warnInvalidHookAccess();
       updateHookTypesDev();
-      return updateDeferredValue(value);
+      return updateDeferredValue(value, initialValue);
     },
     useTransition(): [boolean, (() => void) => void] {
       currentHookNameInDev = 'useTransition';
@@ -3564,11 +3591,11 @@ if (__DEV__) {
       updateHookTypesDev();
       return updateDebugValue(value, formatterFn);
     },
-    useDeferredValue<T>(value: T): T {
+    useDeferredValue<T>(value: T, initialValue?: T): T {
       currentHookNameInDev = 'useDeferredValue';
       warnInvalidHookAccess();
       updateHookTypesDev();
-      return rerenderDeferredValue(value);
+      return rerenderDeferredValue(value, initialValue);
     },
     useTransition(): [boolean, (() => void) => void] {
       currentHookNameInDev = 'useTransition';