From 6cde327c5a6d50ad7f136eab64b42c5774a015e1 Mon Sep 17 00:00:00 2001
From: Matt Carroll <mattca@meta.com>
Date: Wed, 7 Feb 2024 17:58:22 -0800
Subject: [PATCH 1/2] Add useFormStatus pitfall example

---
 .../react-dom/hooks/useFormStatus.md          | 66 +++++++++++++++++--
 1 file changed, 61 insertions(+), 5 deletions(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index 8733ec0ca69..6c39fd441c2 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -47,7 +47,7 @@ export default function App() {
 }
 ```
 
-To get status information, the `Submit` component must be rendered within a `<form>`. The Hook returns information like the <CodeStep step={1}>`pending`</CodeStep> property which tells you if the form is actively submitting. 
+To get status information, the `Submit` component must be rendered within a `<form>`. The Hook returns information like the <CodeStep step={1}>`pending`</CodeStep> property which tells you if the form is actively submitting.
 
 In the above example, `Submit` uses this information to disable `<button>` presses while the form is submitting.
 
@@ -72,7 +72,7 @@ A `status` object with the following properties:
 
 #### Caveats {/*caveats*/}
 
-* The `useFormStatus` Hook must be called from a component that is rendered inside a `<form>`. 
+* The `useFormStatus` Hook must be called from a component that is rendered inside a `<form>`.
 * `useFormStatus` will only return status information for a parent `<form>`. It will not return status information for any `<form>` rendered in that same component or children components.
 
 ---
@@ -129,7 +129,7 @@ export async function submitForm(query) {
   "devDependencies": {}
 }
 ```
-</Sandpack>  
+</Sandpack>
 
 <Pitfall>
 
@@ -151,7 +151,7 @@ Instead call `useFormStatus` from inside a component that is located inside `<fo
 ```js
 function Submit() {
   // ✅ `pending` will be derived from the form that wraps the Submit component
-  const { pending } = useFormStatus(); 
+  const { pending } = useFormStatus();
   return <button disabled={pending}>...</button>;
 }
 
@@ -165,6 +165,62 @@ function Form() {
 }
 ```
 
+When implementing a library or application that involve rich, complex forms, we recommend implementing a Hook similar to `useFormStatus` by using the [form onSubmit event-handler](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event) with [startTransition](/reference/react/startTransition), and (optionally) [useOptimistic](/reference/react/useOptimistic):
+
+
+<Sandpack>
+
+```js src/App.js
+import { useState, startTransition, useOptimistic } from "react";
+import { addCount } from "./api";
+
+export default function Form() {
+  const [pending, setPending] = useState(false);
+  const [count, setCount] = useState(0);
+  const [optimisticCount, optimisticIncreaseCount] = useOptimistic(
+    count,
+    (state) => state + 1
+  );
+  function handleSubmit(event) {
+    event.preventDefault();
+    setPending(true);
+    startTransition(async () => {
+      optimisticIncreaseCount();
+      const updatedCount = await addCount(count);
+      setCount(updatedCount);
+      setPending(false);
+    });
+  }
+  return (
+    <form onSubmit={handleSubmit}>
+      <p>this button has been pressed {"" + optimisticCount}</p>
+      <button disabled={pending}>Submit</button>
+    </form>
+  );
+}
+```
+
+```js src/api.js hidden
+export async function addCount(count) {
+  // simulate a delay from a API/network call
+  await new Promise((res) => setTimeout(res, 500));
+  return count + 1;
+}
+```
+
+```json package.json hidden
+{
+  "dependencies": {
+    "react": "canary",
+    "react-dom": "canary",
+    "react-scripts": "^5.0.0"
+  },
+  "main": "/index.js",
+  "devDependencies": {}
+}
+```
+</Sandpack>
+
 </Pitfall>
 
 ### Read the form data being submitted {/*read-form-data-being-submitted*/}
@@ -246,7 +302,7 @@ export async function submitForm(query) {
   "devDependencies": {}
 }
 ```
-</Sandpack>  
+</Sandpack>
 
 ---
 

From 9c0b1d56d873a452fd8dc4031ba2a1c35d82f0b7 Mon Sep 17 00:00:00 2001
From: Matt Carroll <mattca@meta.com>
Date: Wed, 7 Feb 2024 18:01:23 -0800
Subject: [PATCH 2/2] Fix typo

---
 src/content/reference/react-dom/hooks/useFormStatus.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/reference/react-dom/hooks/useFormStatus.md b/src/content/reference/react-dom/hooks/useFormStatus.md
index 6c39fd441c2..a28e54fd25d 100644
--- a/src/content/reference/react-dom/hooks/useFormStatus.md
+++ b/src/content/reference/react-dom/hooks/useFormStatus.md
@@ -193,7 +193,7 @@ export default function Form() {
   }
   return (
     <form onSubmit={handleSubmit}>
-      <p>this button has been pressed {"" + optimisticCount}</p>
+      <p>This button has been pressed {"" + optimisticCount} times.</p>
       <button disabled={pending}>Submit</button>
     </form>
   );