Implement useDeferredValue initialValue option

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.

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.

packages/react-debug-tools/src/__tests__/ReactHooksInspectionIntegration-test.js

@@ -573,9 +573,7 @@ describe('ReactHooksInspectionIntegration', () => {
 
   it('should support useDeferredValue hook', () => {
     function Foo(props) {
-      React.useDeferredValue('abc', {
-        timeoutMs: 500,
-      });
+      React.useDeferredValue('abc');
       const memoizedValue = React.useMemo(() => 1, []);
       React.useMemo(() => 2, []);
       return <div>{memoizedValue}</div>;

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

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ *
+ * @emails react-core
+ */
+
+'use strict';
+
+import {insertNodesAndExecuteScripts} from '../test-utils/FizzTestUtils';
+
+// Polyfills for test environment
+global.ReadableStream =
+  require('web-streams-polyfill/ponyfill/es6').ReadableStream;
+global.TextEncoder = require('util').TextEncoder;
+
+let act;
+let container;
+let React;
+let ReactDOMServer;
+let ReactDOMClient;
+let useDeferredValue;
+
+describe('ReactDOMFizzForm', () => {
+  beforeEach(() => {
+    jest.resetModules();
+    React = require('react');
+    ReactDOMServer = require('react-dom/server.browser');
+    ReactDOMClient = require('react-dom/client');
+    useDeferredValue = require('react').useDeferredValue;
+    act = require('internal-test-utils').act;
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.removeChild(container);
+  });
+
+  async function readIntoContainer(stream) {
+    const reader = stream.getReader();
+    let result = '';
+    while (true) {
+      const {done, value} = await reader.read();
+      if (done) {
+        break;
+      }
+      result += Buffer.from(value).toString('utf8');
+    }
+    const temp = document.createElement('div');
+    temp.innerHTML = result;
+    insertNodesAndExecuteScripts(temp, container, null);
+  }
+
+  // @gate enableUseDeferredValueInitialArg
+  it('returns initialValue argument, if provided', async () => {
+    function App() {
+      return useDeferredValue('Final', 'Initial');
+    }
+
+    const stream = await ReactDOMServer.renderToReadableStream(<App />);
+    await readIntoContainer(stream);
+    expect(container.textContent).toEqual('Initial');
+
+    // After hydration, it's updated to the final value
+    await act(() => ReactDOMClient.hydrateRoot(container, <App />));
+    expect(container.textContent).toEqual('Final');
+  });
+});

packages/react-reconciler/src/ReactFiberHooks.js

@@ -2640,8 +2640,7 @@ function updateMemo<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, initialValue?: T): T {
@@ -2655,21 +2654,53 @@ 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, initialValue);
   }
 }
 
+function mountDeferredValueImpl<T>(hook: Hook, value: T, initialValue?: T): T {
+  if (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
+    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;
+
+    return initialValue;
+  } else {
+    hook.memoizedState = value;
+    return value;
+  }
+}
+
 function updateDeferredValueImpl<T>(
   hook: Hook,
   prevValue: T,
   value: T,
   initialValue: ?T,
 ): T {
+  // TODO: We should also check if this component is going from
+  // hidden -> visible. If so, it should use the initialValue arg.
+
   const shouldDeferValue = !includesOnlyNonUrgentLanes(renderLanes);
   if (shouldDeferValue) {
     // This is an urgent update. If the value has changed, keep using the

packages/react-reconciler/src/__tests__/ReactDeferredValue-test.js

@@ -306,4 +306,39 @@ describe('ReactDeferredValue', () => {
       );
     });
   });
+
+  // @gate enableUseDeferredValueInitialArg
+  it('supports initialValue argument', async () => {
+    function App() {
+      const value = useDeferredValue('Final', 'Initial');
+      return <Text text={value} />;
+    }
+
+    const root = ReactNoop.createRoot();
+    await act(async () => {
+      root.render(<App />);
+      await waitForPaint(['Initial']);
+      expect(root).toMatchRenderedOutput('Initial');
+    });
+    assertLog(['Final']);
+    expect(root).toMatchRenderedOutput('Final');
+  });
+
+  // @gate enableUseDeferredValueInitialArg
+  it('defers during initial render when initialValue is provided, even if render is not sync', async () => {
+    function App() {
+      const value = useDeferredValue('Final', 'Initial');
+      return <Text text={value} />;
+    }
+
+    const root = ReactNoop.createRoot();
+    await act(async () => {
+      // Initial mount is a transition, but it should defer anyway
+      startTransition(() => root.render(<App />));
+      await waitForPaint(['Initial']);
+      expect(root).toMatchRenderedOutput('Initial');
+    });
+    assertLog(['Final']);
+    expect(root).toMatchRenderedOutput('Final');
+  });
 });

packages/react-reconciler/src/__tests__/ReactHooksWithNoopRenderer-test.js

@@ -3584,9 +3584,7 @@ describe('ReactHooksWithNoopRenderer', () => {
       let _setText;
       function App() {
         const [text, setText] = useState('A');
-        const deferredText = useDeferredValue(text, {
-          timeoutMs: 500,
-        });
+        const deferredText = useDeferredValue(text);
         _setText = setText;
         return (
           <>

packages/react-server/src/ReactFizzHooks.js

@@ -555,7 +555,7 @@ function useSyncExternalStore<T>(
 
 function useDeferredValue<T>(value: T, initialValue?: T): T {
   resolveCurrentlyRenderingComponent();
-  return value;
+  return initialValue !== undefined ? initialValue : value;
 }
 
 function unsupportedStartTransition() {