useFormState: Reuse state from previous form submission

If a Server Action is passed to useFormState, the action may be submitted
before it has hydrated. This will trigger a full page (MPA-style) navigation.
We can transfer the form state to the next page by comparing the key path
of the hook instance.

`ReactServerDOMServer.decodeFormState` is used by the server to extract the form
state from the submitted action. This value can then be passed as an option
when rendering the new page. It must be passed during both SSR and hydration.

```js
const boundAction = await decodeAction(formData, serverManifest);
const promiseForResult = boundAction();
const formState = decodeFormState(formData, serverManifest, promiseForResult);

// SSR
const response = createFromReadableStream(<App />);
const ssrStream = await renderToReadableStream(response, { formState })

// Hydration
hydrateRoot(container, <App />, { formState });
```

If the `formState` option is omitted, then the state won't be transferred to
the next page. However, it must be passed in both places, or in neither;
misconfiguring will result in a hydration mismatch.

Author: acdlite

fixtures/flight-esm/server/region.js

@@ -27,14 +27,14 @@ const React = require('react');
 
 const moduleBasePath = new URL('../src', url.pathToFileURL(__filename)).href;
 
-async function renderApp(res, returnValue) {
+async function renderApp(res, returnValue, formState) {
   const {renderToPipeableStream} = await import('react-server-dom-esm/server');
   const m = await import('../src/App.js');
 
   const App = m.default;
   const root = React.createElement(App);
   // For client-invoked server actions we refresh the tree and return a return value.
-  const payload = returnValue ? {returnValue, root} : root;
+  const payload = {root, returnValue, formState};
   const {pipe} = renderToPipeableStream(payload, moduleBasePath);
   pipe(res);
 }
@@ -80,7 +80,7 @@ app.post('/', bodyParser.text(), async function (req, res) {
       // We handle the error on the client
     }
     // Refresh the client and return the value
-    renderApp(res, result);
+    renderApp(res, result, null);
   } else {
     // This is the progressive enhancement case
     const UndiciRequest = require('undici').Request;
@@ -92,14 +92,16 @@ app.post('/', bodyParser.text(), async function (req, res) {
     });
     const formData = await fakeRequest.formData();
     const action = await decodeAction(formData, moduleBasePath);
+    const result = action();
+    const formState = await decodeFormState(formData, moduleBasePath, result);
     try {
       // Wait for any mutations
-      await action();
+      await result;
     } catch (x) {
       const {setServerState} = await import('../src/ServerState.js');
       setServerState('Error: ' + x.message);
     }
-    renderApp(res, null);
+    renderApp(res, null, formState);
   }
 });
 

fixtures/flight-esm/src/index.js

@@ -25,7 +25,7 @@ async function callServer(id, args) {
   return returnValue;
 }
 
-let data = createFromFetch(
+let {root, formState} = createFromFetch(
   fetch('/', {
     headers: {
       Accept: 'text/x-component',
@@ -43,4 +43,6 @@ function Shell({data}) {
   return root;
 }
 
-ReactDOM.hydrateRoot(document, React.createElement(Shell, {data}));
+ReactDOM.hydrateRoot(document, React.createElement(Shell, {data: root}), {
+  experimental_formState,
+});

packages/react-client/src/ReactFlightReplyClient.js

@@ -7,7 +7,12 @@
  * @flow
  */
 
-import type {Thenable, ReactCustomFormAction} from 'shared/ReactTypes';
+import type {
+  Thenable,
+  FulfilledThenable,
+  RejectedThenable,
+  ReactCustomFormAction,
+} from 'shared/ReactTypes';
 
 import {
   REACT_ELEMENT_TYPE,
@@ -23,10 +28,6 @@ import {
 } from 'shared/ReactSerializationErrors';
 
 import isArray from 'shared/isArray';
-import type {
-  FulfilledThenable,
-  RejectedThenable,
-} from '../../shared/ReactTypes';
 
 import {usedWithSSR} from './ReactFlightClientConfig';
 

packages/react-dom/src/client/ReactDOMLegacy.js

@@ -142,6 +142,7 @@ function legacyCreateRootFromDOMContainer(
       noopOnRecoverableError,
       // TODO(luna) Support hydration later
       null,
+      null,
     );
     container._reactRootContainer = root;
     markContainerAsRoot(root.current, container);

packages/react-dom/src/client/ReactDOMRoot.js

@@ -7,7 +7,7 @@
  * @flow
  */
 
-import type {ReactNodeList} from 'shared/ReactTypes';
+import type {ReactNodeList, ReactFormState} from 'shared/ReactTypes';
 import type {
   FiberRoot,
   TransitionTracingCallbacks,
@@ -21,6 +21,8 @@ import {
   enableHostSingletons,
   allowConcurrentByDefault,
   disableCommentsAsDOMContainers,
+  enableAsyncActions,
+  enableFormActions,
 } from 'shared/ReactFeatureFlags';
 
 import ReactDOMSharedInternals from '../ReactDOMSharedInternals';
@@ -55,6 +57,7 @@ export type HydrateRootOptions = {
   unstable_transitionCallbacks?: TransitionTracingCallbacks,
   identifierPrefix?: string,
   onRecoverableError?: (error: mixed) => void,
+  experimental_formState?: ReactFormState<any> | null,
   ...
 };
 
@@ -302,6 +305,7 @@ export function hydrateRoot(
   let identifierPrefix = '';
   let onRecoverableError = defaultOnRecoverableError;
   let transitionCallbacks = null;
+  let formState = null;
   if (options !== null && options !== undefined) {
     if (options.unstable_strictMode === true) {
       isStrictMode = true;
@@ -321,6 +325,11 @@ export function hydrateRoot(
     if (options.unstable_transitionCallbacks !== undefined) {
       transitionCallbacks = options.unstable_transitionCallbacks;
     }
+    if (enableAsyncActions && enableFormActions) {
+      if (options.experimental_formState !== undefined) {
+        formState = options.experimental_formState;
+      }
+    }
   }
 
   const root = createHydrationContainer(
@@ -334,6 +343,7 @@ export function hydrateRoot(
     identifierPrefix,
     onRecoverableError,
     transitionCallbacks,
+    formState,
   );
   markContainerAsRoot(root.current, container);
   Dispatcher.current = ReactDOMClientDispatcher;

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

@@ -8,7 +8,7 @@
  */
 
 import type {PostponedState} from 'react-server/src/ReactFizzServer';
-import type {ReactNodeList} from 'shared/ReactTypes';
+import type {ReactNodeList, ReactFormState} from 'shared/ReactTypes';
 import type {BootstrapScriptDescriptor} from 'react-dom-bindings/src/server/ReactFizzConfigDOM';
 import type {ImportMap} from '../shared/ReactDOMTypes';
 
@@ -40,6 +40,7 @@ type Options = {
   onPostpone?: (reason: string) => void,
   unstable_externalRuntimeSrc?: string | BootstrapScriptDescriptor,
   importMap?: ImportMap,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 type ResumeOptions = {
@@ -48,6 +49,7 @@ type ResumeOptions = {
   onError?: (error: mixed) => ?string,
   onPostpone?: (reason: string) => void,
   unstable_externalRuntimeSrc?: string | BootstrapScriptDescriptor,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 // TODO: Move to sub-classing ReadableStream.
@@ -116,6 +118,7 @@ function renderToReadableStream(
       onShellError,
       onFatalError,
       options ? options.onPostpone : undefined,
+      options ? options.experimental_formState : undefined,
     );
     if (options && options.signal) {
       const signal = options.signal;
@@ -187,6 +190,7 @@ function resume(
       onShellError,
       onFatalError,
       options ? options.onPostpone : undefined,
+      options ? options.experimental_formState : undefined,
     );
     if (options && options.signal) {
       const signal = options.signal;

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

@@ -7,7 +7,7 @@
  * @flow
  */
 
-import type {ReactNodeList} from 'shared/ReactTypes';
+import type {ReactNodeList, ReactFormState} from 'shared/ReactTypes';
 import type {BootstrapScriptDescriptor} from 'react-dom-bindings/src/server/ReactFizzConfigDOM';
 import type {ImportMap} from '../shared/ReactDOMTypes';
 
@@ -39,6 +39,7 @@ type Options = {
   onPostpone?: (reason: string) => void,
   unstable_externalRuntimeSrc?: string | BootstrapScriptDescriptor,
   importMap?: ImportMap,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 // TODO: Move to sub-classing ReadableStream.
@@ -108,6 +109,7 @@ function renderToReadableStream(
       onShellError,
       onFatalError,
       options ? options.onPostpone : undefined,
+      options ? options.experimental_formState : undefined,
     );
     if (options && options.signal) {
       const signal = options.signal;

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

@@ -8,7 +8,7 @@
  */
 
 import type {PostponedState} from 'react-server/src/ReactFizzServer';
-import type {ReactNodeList} from 'shared/ReactTypes';
+import type {ReactNodeList, ReactFormState} from 'shared/ReactTypes';
 import type {BootstrapScriptDescriptor} from 'react-dom-bindings/src/server/ReactFizzConfigDOM';
 import type {ImportMap} from '../shared/ReactDOMTypes';
 
@@ -40,6 +40,7 @@ type Options = {
   onPostpone?: (reason: string) => void,
   unstable_externalRuntimeSrc?: string | BootstrapScriptDescriptor,
   importMap?: ImportMap,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 type ResumeOptions = {
@@ -48,6 +49,7 @@ type ResumeOptions = {
   onError?: (error: mixed) => ?string,
   onPostpone?: (reason: string) => void,
   unstable_externalRuntimeSrc?: string | BootstrapScriptDescriptor,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 // TODO: Move to sub-classing ReadableStream.
@@ -116,6 +118,7 @@ function renderToReadableStream(
       onShellError,
       onFatalError,
       options ? options.onPostpone : undefined,
+      options ? options.experimental_formState : undefined,
     );
     if (options && options.signal) {
       const signal = options.signal;
@@ -187,6 +190,7 @@ function resume(
       onShellError,
       onFatalError,
       options ? options.onPostpone : undefined,
+      options ? options.experimental_formState : undefined,
     );
     if (options && options.signal) {
       const signal = options.signal;

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

@@ -8,7 +8,7 @@
  */
 
 import type {Request, PostponedState} from 'react-server/src/ReactFizzServer';
-import type {ReactNodeList} from 'shared/ReactTypes';
+import type {ReactNodeList, ReactFormState} from 'shared/ReactTypes';
 import type {Writable} from 'stream';
 import type {BootstrapScriptDescriptor} from 'react-dom-bindings/src/server/ReactFizzConfigDOM';
 import type {Destination} from 'react-server/src/ReactServerStreamConfigNode';
@@ -53,6 +53,7 @@ type Options = {
   onPostpone?: (reason: string) => void,
   unstable_externalRuntimeSrc?: string | BootstrapScriptDescriptor,
   importMap?: ImportMap,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 type ResumeOptions = {
@@ -62,6 +63,7 @@ type ResumeOptions = {
   onAllReady?: () => void,
   onError?: (error: mixed) => ?string,
   onPostpone?: (reason: string) => void,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 type PipeableStream = {
@@ -96,6 +98,7 @@ function createRequestImpl(children: ReactNodeList, options: void | Options) {
     options ? options.onShellError : undefined,
     undefined,
     options ? options.onPostpone : undefined,
+    options ? options.experimental_formState : undefined,
   );
 }
 
@@ -156,6 +159,7 @@ function resumeRequestImpl(
     options ? options.onShellError : undefined,
     undefined,
     options ? options.onPostpone : undefined,
+    options ? options.experimental_formState : undefined,
   );
 }
 

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

@@ -7,7 +7,7 @@
  * @flow
  */
 
-import type {ReactNodeList} from 'shared/ReactTypes';
+import type {ReactNodeList, ReactFormState} from 'shared/ReactTypes';
 import type {BootstrapScriptDescriptor} from 'react-dom-bindings/src/server/ReactFizzConfigDOM';
 import type {PostponedState} from 'react-server/src/ReactFizzServer';
 import type {ImportMap} from '../shared/ReactDOMTypes';
@@ -40,6 +40,7 @@ type Options = {
   onPostpone?: (reason: string) => void,
   unstable_externalRuntimeSrc?: string | BootstrapScriptDescriptor,
   importMap?: ImportMap,
+  experimental_formState?: ReactFormState<any> | null,
 };
 
 type StaticResult = {
@@ -96,6 +97,7 @@ function prerender(
       undefined,
       onFatalError,
       options ? options.onPostpone : undefined,
+      options ? options.experimental_formState : undefined,
     );
     if (options && options.signal) {
       const signal = options.signal;