Remove hard requirement of mutual exclusivity

Author: brophdawg11

.changeset/raw-payload-submission.md

@@ -2,21 +2,45 @@
 "react-router-dom": minor
 ---
 
-- Support submission of raw payloads through `useSubmit`/`fetcher.submit` by opting out of serialization into `request.formData` using `encType: null`. When opting-out of serialization, your data will be passed to the action in a new `payload` parameter:
+- Support better submission and control of serialization of raw payloads through `useSubmit`/`fetcher.submit`. The default `encType` will still be `application/x-www-form-urlencoded` as it is today, but actions will now also receive a raw `payload` parameter when you submit a raw value (not an HTML element, `FormData`, or `URLSearchParams`).
+
+The default behavior will still serialize into `FormData`:
+
+```jsx
+function Component() {
+  let submit = useSubmit();
+  submit({ key: "value" });
+  // navigation.formEncType => "application/x-www-form-urlencoded"
+  // navigation.formData    => FormData instance
+  // navigation.payload     => { key: "Value" }
+}
+
+function action({ request, payload }) {
+  // request.headers.get("Content-Type") => "application/x-www-form-urlencoded"
+  // request.formData                    => FormData instance
+  // payload                             => { key: 'value' }
+}
+```
+
+You may opt out of this default serialization using `encType: null`:
 
 ```jsx
 function Component() {
   let submit = useSubmit();
   submit({ key: "value" }, { encType: null });
+  // navigation.formEncType => null
+  // navigation.formData    => undefined
+  // navigation.payload     => { key: "Value" }
 }
 
 function action({ request, payload }) {
-  // payload      => { key: 'value' }
-  // request.body => null
+  // request.headers.get("Content-Type") => null
+  // request.formData                    => undefined
+  // payload                             => { key: 'value' }
 }
 ```
 
-Since the default behavior in `useSubmit` today is to serialize to `application/x-www-form-urlencoded`, that will remain the behavior for `encType:undefined` in v6. But in v7, we plan to change the default behavior for `undefined` to skip serialization. In order to better prepare for this change, we encourage developers to add explicit content types to scenarios in which they are submitting raw JSON objects:
+_Note: we plan to change the default behavior of `{ encType: undefined }` to match this "no serialization" behavior in React Router v7. In order to better prepare for this change, we encourage developers to add explicit content types to scenarios in which they are submitting raw JSON objects:_
 
 ```jsx
 function Component() {
@@ -36,34 +60,46 @@ function Component() {
 function Component() {
   let submit = useSubmit();
   submit({ key: "value" }, { encType: "application/json" });
+  // navigation.formEncType => "application/json"
+  // navigation.formData    => undefined
+  // navigation.payload     => { key: "Value" }
 }
 
 function action({ request, payload }) {
-  // payload              => { key: 'value' }
-  // await request.json() => {"key":"value"}
+  // request.headers.get("Content-Type") => "application/json"
+  // request.json                        => { key: 'value' }
+  // payload                             => { key: 'value' }
 }
 ```
 
 ```js
 function Component() {
   let submit = useSubmit();
   submit({ key: "value" }, { encType: "application/x-www-form-urlencoded" });
+  // navigation.formEncType => "application/x-www-form-urlencoded"
+  // navigation.formData    => FormData instance
+  // navigation.payload     => { key: "Value" }
 }
 
 function action({ request, payload }) {
-  // payload                  => { key: 'value' }
-  // await request.formData() => FormData instance with a single entry of key=value
+  // request.headers.get("Content-Type") => "application/x-www-form-urlencoded"
+  // request.formData                    => { key: 'value' }
+  // payload                             => { key: 'value' }
 }
 ```
 
 ```js
 function Component() {
   let submit = useSubmit();
   submit("Plain ol' text", { encType: "text/plain" });
+  // navigation.formEncType => "text/plain"
+  // navigation.formData    => undefined
+  // navigation.payload     => "Plain ol' text"
 }
 
 function action({ request, payload }) {
-  // payload              => "Plain ol' text"
-  // await request.text() => "Plain ol' text"
+  // request.headers.get("Content-Type") => "text/plain"
+  // request.text                        => "Plain ol' text"
+  // payload                             => "Plain ol' text"
 }
 ```

packages/react-router-dom/__tests__/data-browser-router-test.tsx

@@ -9,7 +9,7 @@ import {
   prettyDOM,
 } from "@testing-library/react";
 import "@testing-library/jest-dom";
-import type { ErrorResponse } from "@remix-run/router";
+import { ErrorResponse, IDLE_NAVIGATION, Navigation } from "@remix-run/router";
 import type { RouteObject } from "react-router-dom";
 import {
   Form,
@@ -3133,13 +3133,18 @@ function testDomRouter(
       it("serializes formData on submit(object) submissions", async () => {
         let actionSpy = jest.fn();
         let payload = { a: "1", b: "2" };
+        let navigation;
         let router = createTestRouter(
           [
             {
               path: "/",
               action: actionSpy,
               Component() {
                 let submit = useSubmit();
+                let n = useNavigation();
+                if (n.state === "submitting") {
+                  navigation = n;
+                }
                 return (
                   <button onClick={() => submit(payload, { method: "post" })}>
                     Submit
@@ -3153,22 +3158,34 @@ function testDomRouter(
         render(<RouterProvider router={router} />);
 
         fireEvent.click(screen.getByText("Submit"));
-        let formData = await actionSpy.mock.calls[0][0].request.formData();
-        expect(formData.get("a")).toBe("1");
-        expect(formData.get("b")).toBe("2");
-        expect(actionSpy.mock.calls[0][0].payload).toBe(undefined);
+        expect(navigation.formData?.get("a")).toBe("1");
+        expect(navigation.formData?.get("b")).toBe("2");
+        expect(navigation.payload).toBe(payload);
+        let { request, payload: actionPayload } = actionSpy.mock.calls[0][0];
+        expect(request.headers.get("Content-Type")).toMatchInlineSnapshot(
+          `"application/x-www-form-urlencoded;charset=UTF-8"`
+        );
+        let actionFormData = await request.formData();
+        expect(actionFormData.get("a")).toBe("1");
+        expect(actionFormData.get("b")).toBe("2");
+        expect(actionPayload).toBe(payload);
       });
 
       it("serializes formData on submit(object)/encType:application/x-www-form-urlencoded submissions", async () => {
         let actionSpy = jest.fn();
         let payload = { a: "1", b: "2" };
+        let navigation;
         let router = createTestRouter(
           [
             {
               path: "/",
               action: actionSpy,
               Component() {
                 let submit = useSubmit();
+                let n = useNavigation();
+                if (n.state === "submitting") {
+                  navigation = n;
+                }
                 return (
                   <button
                     onClick={() =>
@@ -3189,26 +3206,34 @@ function testDomRouter(
         render(<RouterProvider router={router} />);
 
         fireEvent.click(screen.getByText("Submit"));
-        let request = actionSpy.mock.calls[0][0].request;
-        expect(request.headers.get("Content-Type")).toBe(
-          "application/x-www-form-urlencoded;charset=UTF-8"
+        expect(navigation.formData?.get("a")).toBe("1");
+        expect(navigation.formData?.get("b")).toBe("2");
+        expect(navigation.payload).toBe(payload);
+        let { request, payload: actionPayload } = actionSpy.mock.calls[0][0];
+        expect(request.headers.get("Content-Type")).toMatchInlineSnapshot(
+          `"application/x-www-form-urlencoded;charset=UTF-8"`
         );
-        let formData = await request.formData();
-        expect(formData.get("a")).toBe("1");
-        expect(formData.get("b")).toBe("2");
-        expect(actionSpy.mock.calls[0][0].payload).toBe(undefined);
+        let actionFormData = await request.formData();
+        expect(actionFormData.get("a")).toBe("1");
+        expect(actionFormData.get("b")).toBe("2");
+        expect(actionPayload).toBe(payload);
       });
 
       it("serializes JSON on submit(object)/encType:application/json submissions", async () => {
         let actionSpy = jest.fn();
         let payload = { a: "1", b: "2" };
+        let navigation;
         let router = createTestRouter(
           [
             {
               path: "/",
               action: actionSpy,
               Component() {
                 let submit = useSubmit();
+                let n = useNavigation();
+                if (n.state === "submitting") {
+                  navigation = n;
+                }
                 return (
                   <button
                     onClick={() =>
@@ -3229,22 +3254,29 @@ function testDomRouter(
         render(<RouterProvider router={router} />);
 
         fireEvent.click(screen.getByText("Submit"));
-        let request = actionSpy.mock.calls[0][0].request;
+        expect(navigation.formData).toBe(undefined);
+        expect(navigation.payload).toBe(payload);
+        let { request, payload: actionPayload } = actionSpy.mock.calls[0][0];
         expect(request.headers.get("Content-Type")).toBe("application/json");
         expect(await request.json()).toEqual({ a: "1", b: "2" });
-        expect(actionSpy.mock.calls[0][0].payload).toBe(payload);
+        expect(actionPayload).toBe(payload);
       });
 
       it("serializes text on submit(object)/encType:text/plain submissions", async () => {
         let actionSpy = jest.fn();
         let payload = "look ma, no formData!";
+        let navigation;
         let router = createTestRouter(
           [
             {
               path: "/",
               action: actionSpy,
               Component() {
                 let submit = useSubmit();
+                let n = useNavigation();
+                if (n.state === "submitting") {
+                  navigation = n;
+                }
                 return (
                   <button
                     onClick={() =>
@@ -3265,22 +3297,29 @@ function testDomRouter(
         render(<RouterProvider router={router} />);
 
         fireEvent.click(screen.getByText("Submit"));
-        let request = actionSpy.mock.calls[0][0].request;
+        expect(navigation.formData).toBe(undefined);
+        expect(navigation.payload).toBe(payload);
+        let { request, payload: actionPayload } = actionSpy.mock.calls[0][0];
         expect(request.headers.get("Content-Type")).toBe("text/plain");
         expect(await request.text()).toEqual(payload);
-        expect(actionSpy.mock.calls[0][0].payload).toBe(payload);
+        expect(actionPayload).toBe(payload);
       });
 
       it("does not serialize formData on submit(object)/encType:null submissions", async () => {
         let actionSpy = jest.fn();
         let payload;
+        let navigation;
         let router = createTestRouter(
           [
             {
               path: "/",
               action: actionSpy,
               Component() {
                 let submit = useSubmit();
+                let n = useNavigation();
+                if (n.state === "submitting") {
+                  navigation = n;
+                }
                 return (
                   <button
                     onClick={() =>
@@ -3299,18 +3338,24 @@ function testDomRouter(
 
         payload = "look ma no formData!";
         fireEvent.click(screen.getByText("Submit"));
+        expect(navigation.formData).toBeUndefined();
+        expect(navigation.payload).toBe(payload);
         expect(actionSpy.mock.calls[0][0].request.body).toBe(null);
         expect(actionSpy.mock.calls[0][0].payload).toBe(payload);
         actionSpy.mockReset();
 
         payload = { a: "1", b: "2" };
         fireEvent.click(screen.getByText("Submit"));
+        expect(navigation.formData).toBeUndefined();
+        expect(navigation.payload).toBe(payload);
         expect(actionSpy.mock.calls[0][0].request.body).toBe(null);
         expect(actionSpy.mock.calls[0][0].payload).toBe(payload);
         actionSpy.mockReset();
 
         payload = [1, 2, 3, 4, 5];
         fireEvent.click(screen.getByText("Submit"));
+        expect(navigation.formData).toBeUndefined();
+        expect(navigation.payload).toBe(payload);
         expect(actionSpy.mock.calls[0][0].request.body).toBe(null);
         expect(actionSpy.mock.calls[0][0].payload).toBe(payload);
         actionSpy.mockReset();

packages/react-router-dom/dom.ts

@@ -283,6 +283,10 @@ export function getFormSubmissionInfo(
           formData.append(name, value);
         }
       } else if (target != null) {
+        // When a raw object is sent - even though we encode it into formData,
+        // we still expose it as payload so it aligns with the behavior if
+        // encType were application/json or text/plain
+        payload = target;
         // To be deprecated in v7 so the default behavior of undefined matches
         // the null behavior of no-serialization
         for (let name of Object.keys(target)) {

packages/router/router.ts

@@ -3178,28 +3178,16 @@ function normalizeNavigateOptions(
     };
   }
 
-  // formData/payload are mutually exclusive
-  if (
-    (opts.formData == null && opts.payload === undefined) ||
-    (opts.formData != null && opts.payload !== undefined)
-  ) {
-    return {
-      path,
-      error: getInternalRouterError(400, { type: "formData-payload" }),
-    };
-  }
-
   // Create a Submission on non-GET navigations
   let submission: Submission;
   let rawFormMethod = opts.formMethod || "get";
   let formMethod = normalizeFormMethod
     ? (rawFormMethod.toUpperCase() as V7_FormMethod)
     : (rawFormMethod.toLowerCase() as FormMethod);
   let formAction = stripHashFromPath(path);
-  let formData: FormData;
 
   // User opted-out of serialization, so just pass along the payload directly
-  if (opts.payload !== undefined) {
+  if (opts.payload !== undefined && opts.formData == null) {
     // Any payload encType's besides these pass through as a normal payload and
     // get serialized in createClientSideRequest since they are not represented
     // via formData
@@ -3212,18 +3200,17 @@ function normalizeNavigateOptions(
     };
 
     return { path, submission };
-  } else {
-    // We know this exists due to the mutually exclusive check above
-    formData = opts.formData!;
   }
 
+  invariant(opts.formData, "Expected a FormData instance");
+
   submission = {
     formMethod,
     formAction,
     formEncType:
       (opts && opts.formEncType) || "application/x-www-form-urlencoded",
-    formData,
-    payload: undefined,
+    formData: opts.formData,
+    payload: opts.payload,
   };
 
   if (isMutationMethod(submission.formMethod)) {
@@ -3232,7 +3219,7 @@ function normalizeNavigateOptions(
 
   // Flatten submission onto URLSearchParams for GET submissions
   let parsedPath = parsePath(path);
-  let searchParams = convertFormDataToSearchParams(formData);
+  let searchParams = convertFormDataToSearchParams(opts.formData);
   // On GET navigation submissions we can drop the ?index param from the
   // resulting location since all loaders will run.  But fetcher GET submissions
   // only run a single loader so we need to preserve any incoming ?index params
@@ -4037,7 +4024,7 @@ function getInternalRouterError(
     pathname?: string;
     routeId?: string;
     method?: string;
-    type?: "defer-action" | "formData-payload";
+    type?: "defer-action";
   } = {}
 ) {
   let statusText = "Unknown Server Error";
@@ -4052,10 +4039,6 @@ function getInternalRouterError(
         `so there is no way to handle the request.`;
     } else if (type === "defer-action") {
       errorMessage = "defer() is not supported in actions";
-    } else if (type === "formData-payload") {
-      errorMessage =
-        "You must include either `formData` or `payload` on a mutation " +
-        "submission navigation, but not both";
     }
   } else if (status === 403) {
     statusText = "Forbidden";