Add stub for experimental_useFormStatus (#26719)

This wires up, but does not yet implement, an experimental hook called
useFormStatus. The hook is imported from React DOM, not React, because
it represents DOM-specific state — its return type includes FormData as
one of its fields. Other renderers that implement similar methods would
use their own renderer-specific types.

The API is prefixed and only available in the experimental channel.

It can only be used from client (browser, SSR) components, not Server
Components.

packages/react-dom/index.classic.fb.js

@@ -31,6 +31,7 @@ export {
   unstable_createEventHandle,
   unstable_renderSubtreeIntoContainer,
   unstable_runWithPriority, // DO NOT USE: Temporarily exposed to migrate off of Scheduler.runWithPriority.
+  useFormStatus as experimental_useFormStatus,
   prefetchDNS,
   preconnect,
   preload,

packages/react-dom/index.experimental.js

@@ -20,6 +20,7 @@ export {
   unstable_batchedUpdates,
   unstable_renderSubtreeIntoContainer,
   unstable_runWithPriority, // DO NOT USE: Temporarily exposed to migrate off of Scheduler.runWithPriority.
+  useFormStatus as experimental_useFormStatus,
   prefetchDNS,
   preconnect,
   preload,

packages/react-dom/index.js

@@ -23,6 +23,7 @@ export {
   unstable_createEventHandle,
   unstable_renderSubtreeIntoContainer,
   unstable_runWithPriority, // DO NOT USE: Temporarily exposed to migrate off of Scheduler.runWithPriority.
+  useFormStatus as experimental_useFormStatus,
   prefetchDNS,
   preconnect,
   preload,

packages/react-dom/index.modern.fb.js

@@ -16,6 +16,7 @@ export {
   unstable_batchedUpdates,
   unstable_createEventHandle,
   unstable_runWithPriority, // DO NOT USE: Temporarily exposed to migrate off of Scheduler.runWithPriority.
+  useFormStatus as experimental_useFormStatus,
   prefetchDNS,
   preconnect,
   preload,

packages/react-dom/src/ReactDOMFormActions.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ *
+ * @flow
+ */
+
+import {enableAsyncActions, enableFormActions} from 'shared/ReactFeatureFlags';
+
+type FormStatusNotPending = {|
+  pending: false,
+  data: null,
+  method: null,
+  action: null,
+|};
+
+type FormStatusPending = {|
+  pending: true,
+  data: FormData,
+  method: string,
+  action: string | (FormData => void | Promise<void>),
+|};
+
+export type FormStatus = FormStatusPending | FormStatusNotPending;
+
+// Since the "not pending" value is always the same, we can reuse the
+// same object across all transitions.
+const sharedNotPendingObject = {
+  pending: false,
+  data: null,
+  method: null,
+  action: null,
+};
+
+const NotPending: FormStatus = __DEV__
+  ? Object.freeze(sharedNotPendingObject)
+  : sharedNotPendingObject;
+
+export function useFormStatus(): FormStatus {
+  if (!(enableFormActions && enableAsyncActions)) {
+    throw new Error('Not implemented.');
+  } else {
+    // TODO: This isn't fully implemented yet but we return a correctly typed
+    // value so we can test that the API is exposed and gated correctly. The
+    // real implementation will access the status via the dispatcher.
+    return NotPending;
+  }
+}

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

@@ -19,6 +19,7 @@ let container;
 let React;
 let ReactDOMServer;
 let ReactDOMClient;
+let useFormStatus;
 
 describe('ReactDOMFizzForm', () => {
   beforeEach(() => {
@@ -26,6 +27,7 @@ describe('ReactDOMFizzForm', () => {
     React = require('react');
     ReactDOMServer = require('react-dom/server.browser');
     ReactDOMClient = require('react-dom/client');
+    useFormStatus = require('react-dom').experimental_useFormStatus;
     act = require('internal-test-utils').act;
     container = document.createElement('div');
     document.body.appendChild(container);
@@ -360,4 +362,20 @@ describe('ReactDOMFizzForm', () => {
     expect(buttonRef.current.hasAttribute('formMethod')).toBe(false);
     expect(buttonRef.current.hasAttribute('formTarget')).toBe(false);
   });
+
+  // @gate enableFormActions
+  // @gate enableAsyncActions
+  it('useFormStatus is not pending during server render', async () => {
+    function App() {
+      const {pending} = useFormStatus();
+      return 'Pending: ' + pending;
+    }
+
+    const stream = await ReactDOMServer.renderToReadableStream(<App />);
+    await readIntoContainer(stream);
+    expect(container.textContent).toBe('Pending: false');
+
+    await act(() => ReactDOMClient.hydrateRoot(container, <App />));
+    expect(container.textContent).toBe('Pending: false');
+  });
 });

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

@@ -39,6 +39,7 @@ describe('ReactDOMForm', () => {
   let Suspense;
   let startTransition;
   let textCache;
+  let useFormStatus;
 
   beforeEach(() => {
     jest.resetModules();
@@ -51,6 +52,7 @@ describe('ReactDOMForm', () => {
     useState = React.useState;
     Suspense = React.Suspense;
     startTransition = React.startTransition;
+    useFormStatus = ReactDOM.experimental_useFormStatus;
     container = document.createElement('div');
     document.body.appendChild(container);
 
@@ -846,4 +848,20 @@ describe('ReactDOMForm', () => {
     assertLog(['Oh no!', 'Oh no!']);
     expect(container.textContent).toBe('Oh no!');
   });
+
+  // @gate enableFormActions
+  // @gate enableAsyncActions
+  it('useFormStatus exists', async () => {
+    // This API isn't fully implemented yet. This just tests that it's wired
+    // up correctly.
+
+    function App() {
+      const {pending} = useFormStatus();
+      return 'Pending: ' + pending;
+    }
+
+    const root = ReactDOMClient.createRoot(container);
+    await act(() => root.render(<App />));
+    expect(container.textContent).toBe('Pending: false');
+  });
 });

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

@@ -56,6 +56,7 @@ import {
 import Internals from '../ReactDOMSharedInternals';
 
 export {prefetchDNS, preconnect, preload, preinit} from '../ReactDOMFloat';
+export {useFormStatus} from '../ReactDOMFormActions';
 
 if (__DEV__) {
   if (