Merge branch 'main' into release-next

Author: brophdawg11

contributors.yml

@@ -14,6 +14,7 @@
 - AmRo045
 - amsal
 - andreiduca
+- antonmontrezor
 - appden
 - arnassavickas
 - aroyan
@@ -124,6 +125,7 @@
 - lordofthecactus
 - LordThi
 - loun4
+- lounsbrough
 - lpaube
 - lqze
 - lukerSpringTree
@@ -191,6 +193,7 @@
 - thisiskartik
 - thomasverleye
 - ThornWu
+- tiborbarsi
 - timdorr
 - TkDodo
 - tkindy

docs/components/routes.md

@@ -17,7 +17,7 @@ interface RoutesProps {
 </Routes>;
 ```
 
-<docs-info>If you're using a data router like [`createBrowserRouter`][createbrowserrouter] it is uncommon to use this component as it does not participate in data loading.</docs-info>
+<docs-info>If you're using a data router like [`createBrowserRouter`][createbrowserrouter] it is uncommon to use this component as routes defined as part of a descendant `<Routes>` tree cannot leverage the [Data APIs][data-apis] available to [`RouterProvider`][router-provider] apps. You **can and should** use this component within your `RouterProvider` application [while you are migrating][migrating-to-router-provider].</docs-info>
 
 Whenever the location changes, `<Routes>` looks through all its child routes to find the best match and renders that branch of the UI. `<Route>` elements may be nested to indicate nested UI, which also correspond to nested URL paths. Parent routes render their child routes by rendering an [`<Outlet>`][outlet].
 
@@ -38,3 +38,6 @@ Whenever the location changes, `<Routes>` looks through all its child routes to
 [outlet]: ./outlet
 [use-route]: ../hooks/use-routes
 [createbrowserrouter]: ../routers/create-browser-router
+[data-apis]: ../routers/picking-a-router#data-apis
+[router-provider]: ../routers/router-provider
+[migrating-to-router-provider]: ../upgrading/v6-data

docs/guides/ssr.md

@@ -143,7 +143,7 @@ Once we've sent the HTML back to the browser, we'll need to "hydrate" the applic
 
 ```jsx filename=entry-client.jsx lines=[10-15]
 import * as React from "react";
-import ReactDOM from "react-dom/client";
+import * as ReactDOM from "react-dom/client";
 import {
   createBrowserRouter,
   RouterProvider,
@@ -275,7 +275,7 @@ app.listen(3000);
 And finally, you'll need a similar file to "hydrate" the app with your JavaScript bundle that includes the very same `App` component. Note the use of `BrowserRouter` instead of `StaticRouter`.
 
 ```js filename=client.entry.js
-import ReactDOM from "react-dom";
+import * as ReactDOM from "react-dom";
 import { BrowserRouter } from "react-router-dom";
 import App from "./App";
 

docs/hooks/use-navigate.md

@@ -4,7 +4,7 @@ title: useNavigate
 
 # `useNavigate`
 
-<docs-warning>It's usually better to use [`redirect`][redirect] in loaders and actions than this hook</docs-warning>
+<docs-warning>It's usually better to use [`redirect`][redirect] in [`loaders`][loaders] and [`actions`][actions] than this hook</docs-warning>
 
 The `useNavigate` hook returns a function that lets you navigate programmatically, for example in an effect:
 
@@ -50,3 +50,5 @@ The `navigate` function has two signatures:
 If using `replace: true`, the navigation will replace the current entry in the history stack instead of adding a new one.
 
 [redirect]: ../fetch/redirect
+[loaders]: ../route/loader
+[actions]: ../route/action

docs/route/action.md

@@ -129,6 +129,62 @@ You can `throw` in your action to break out of the current call stack (stop runn
 
 For more details and expanded use cases, read the [errorElement][errorelement] documentation.
 
+## Handling multiple actions per route
+
+A fairly common question that pops up is _"What if I need to handle multiple different behaviors in my action?"_ There's a few ways to accomplish this, but usually the simplest is to put a `name`/`value` on your `<button type="submit">` and use that in the action to decide which code to execute (that's right - submitting [buttons][button] can have name/value attributes!):
+
+```jsx lines=[3,5,10,30-32,42-44]
+async function action({ request }) {
+  let formData = await request.formData();
+  let intent = formData.get("intent");
+
+  if (intent === "edit") {
+    await editSong(formData);
+    return { ok: true };
+  }
+
+  if (intent === "add") {
+    await addSong(formData);
+    return { ok: true };
+  }
+
+  throw json(
+    { message: "Invalid intent" },
+    { status: 400 }
+  );
+}
+
+function Component() {
+  let song = useLoaderData();
+
+  // When the song exists, show an edit form
+  if (song) {
+    return (
+      <Form method="post">
+        <p>Edit song lyrics:</p>
+        {/* Edit song inputs */}
+        <button type="submit" name="intent" value="edit">
+          Edit
+        </button>
+      </Form>
+    );
+  }
+
+  // Otherwise show a form to add a new song
+  return (
+    <Form method="post">
+      <p>Add new lyrics:</p>
+      {/* Add song inputs */}
+      <button type="submit" name="intent" value="add">
+        Add
+      </button>
+    </Form>
+  );
+}
+```
+
+If a button name/value isn't right for your use case, you could also use a hidden input to send and `intent` or you could submit different HTTP methods via the [`<Form method>`][form-method] prop (`POST` for add, `PUT`/`PATCH` for edit, `DELETE` for remove).
+
 [loader]: ./loader
 [pickingarouter]: ../routers/picking-a-router
 [dynamicsegments]: ./route#dynamic-segments
@@ -146,3 +202,5 @@ For more details and expanded use cases, read the [errorElement][errorelement] d
 [useactiondata]: ../hooks/use-action-data
 [returningresponses]: ./loader#returning-responses
 [createbrowserrouter]: ../routers/create-browser-router
+[button]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button
+[form-method]: ../components/form#method

docs/start/_tutorial.md

@@ -74,7 +74,7 @@ Actually, that "!" doesn't look boring at all. This is pretty exciting. We sat o
 Finally, go make sure `index.js` or `main.jsx` (depending on the bundler you used) is actually boring:
 
 ```tsx filename=src/main.jsx
-import ReactDOM from "react-dom/client";
+import * as ReactDOM from "react-dom/client";
 import App from "./App";
 
 const root = ReactDOM.createRoot(
@@ -98,7 +98,7 @@ npm run dev
 First things first, we want to connect your app to the browser's URL: import `BrowserRouter` and render it around your whole app.
 
 ```tsx lines=[2,9-11] filename=src/main.jsx
-import ReactDOM from "react-dom/client";
+import * as ReactDOM from "react-dom/client";
 import { BrowserRouter } from "react-router-dom";
 import App from "./App";
 
@@ -177,7 +177,7 @@ export default function Invoices() {
 Finally, let's teach React Router how to render our app at different URLs by creating our first "Route Config" inside of `main.jsx` or `index.js`.
 
 ```tsx lines=[2,4-5,8-9,15-21] filename=src/main.jsx
-import ReactDOM from "react-dom/client";
+import * as ReactDOM from "react-dom/client";
 import {
   BrowserRouter,
   Routes,
@@ -217,7 +217,7 @@ Let's get some automatic, persistent layout handling by doing just two things:
 First let's nest the routes. Right now the expenses and invoices routes are siblings to the app, we want to make them _children_ of the app route:
 
 ```jsx lines=[17-20] filename=src/main.jsx
-import ReactDOM from "react-dom/client";
+import * as ReactDOM from "react-dom/client";
 import {
   BrowserRouter,
   Routes,

docs/start/overview.md

@@ -18,7 +18,7 @@ This enables faster user experiences because the browser doesn't need to request
 Client side routing is enabled by creating a `Router` and linking/submitting to pages with `Link` and `<Form>`:
 
 ```jsx [10,16,27]
-import React from "react";
+import * as React from "react";
 import { createRoot } from "react-dom/client";
 import {
   createBrowserRouter,
@@ -78,7 +78,7 @@ createBrowserRouter(
           element={<Login />}
           loader={redirectIfUser}
         />
-        <Route path="logout" />
+        <Route path="logout" action={logoutUser} />
       </Route>
     </Route>
   )

docs/start/tutorial.md

@@ -68,8 +68,8 @@ The `main.jsx` file is the entry point. Open it up and we'll put React Router on
 👉 **Create and render a [browser router][createbrowserrouter] in `main.jsx`**
 
 ```jsx lines=[3-6,9-14,18] filename=src/main.jsx
-import React from "react";
-import ReactDOM from "react-dom/client";
+import * as React from "react";
+import * as ReactDOM from "react-dom/client";
 import {
   createBrowserRouter,
   RouterProvider,
@@ -1487,10 +1487,19 @@ You could certainly do this as a controlled component, but you'll end up with mo
 
 Notice how controlling the input requires three points of synchronization now instead of just one. The behavior is identical but the code is more complex.
 
-```jsx filename=src/routes/root.jsx lines=[1,6,9-11,25-28]
+```jsx filename=src/routes/root.jsx lines=[1,6,15,18-20,34-37]
 import { useEffect, useState } from "react";
 // existing code
 
+export async function loader({ request }) {
+  const url = new URL(request.url);
+  const q = url.searchParams.get("q") || "";
+  const contacts = await getContacts(q);
+  return { contacts, q };
+}
+
+// existing code
+
 export default function Root() {
   const { contacts, q } = useLoaderData();
   const [query, setQuery] = useState(q);
@@ -1911,6 +1920,7 @@ And for our final trick, many folks prefer to configure their routes with JSX. Y
 import {
   createRoutesFromElements,
   createBrowserRouter,
+  Route,
 } from "react-router-dom";
 
 const router = createBrowserRouter(

docs/upgrading/v5.md

@@ -1,6 +1,6 @@
 ---
 title: Upgrading from v5
-order: 1
+order: 2
 ---
 
 # Upgrading from v5