Add future.v7_relativeSplatPath flag

.changeset/relative-splat-path.md

@@ -0,0 +1,138 @@
+---
+"react-router-dom-v5-compat": minor
+"react-router-native": minor
+"react-router-dom": minor
+"react-router": minor
+"@remix-run/router": minor
+---
+
+Add a new `future.v7_relativeSplatPath` flag to implenent a breaking bug fix to relative routing when inside a splat route.
+
+This fix was originally added in [#10983](https://github.com/remix-run/react-router/issues/10983) and was later reverted in [#11078](https://github.com/remix-run/react-router/issues/110788) because it was determined that a large number of existing applications were relying on the buggy behavior (see [#11052](https://github.com/remix-run/react-router/issues/11052))
+
+**The Bug**
+The buggy behavior is that without this flag, the default behavior when resolving relative paths is to _ignore_ any splat (`*`) portion of the current route path.
+
+**The Background**
+This decision was originally made thinking that it would make the concept of nested different sections of your apps in `<Routes>` easier if relative routing would _replace_ the current splat:
+
+```jsx
+<BrowserRouter>
+  <Routes>
+    <Route path="/" element={<Home />} />
+    <Route path="dashboard/*" element={<Dashboard />} />
+  </Routes>
+</BrowserRouter>
+```
+
+Any paths like `/dashboard`, `/dashboard/team`, `/dashboard/projects` will match the `Dashboard` route. The dashboard component itself can then render nested `<Routes>`:
+
+```jsx
+function Dashboard() {
+  return (
+    <div>
+      <h2>Dashboard</h2>
+      <nav>
+        <Link to="/">Dashboard Home</Link>
+        <Link to="team">Team</Link>
+        <Link to="projects">Projects</Link>
+      </nav>
+
+      <Routes>
+        <Route path="/" element={<DashboardHome />} />
+        <Route path="team" element={<DashboardTeam />} />
+        <Route path="projects" element={<DashboardProjects />} />
+      </Routes>
+    </div>
+  );
+}
+```
+
+Now, all links and route paths are relative to the router above them. This makes code splitting and compartmentalizing your app really easy. You could render the `Dashboard` as its own independent app, or embed it into your large app without making any changes to it.
+
+**The Problem**
+
+The problem is that this concept of ignoring part of a pth breaks a lot of other assumptions in React Router - namely that `"."` always means the current location pathname for that route. When we ignore the splat portion, we start getting invalid paths when using `"."`:
+
+```jsx
+// If we are on URL /dashboard/team, and we want to link to /dashboard/team:
+function DashboardTeam() {
+  // ❌ This is broken and results in <a href="/dashboard">
+  return <Link to=".">A broken link to the Current URL</Link>;
+
+  // ✅ This is fixed but super unintuitive since we're already at /dashboard/team!
+  return <Link to="./team">A broken link to the Current URL</Link>;
+}
+```
+
+We've also introduced an issue that we can no longer move our `DashboardTeam` component around our route hierarchy easily - since it behaves differently if we're underneath a non-splat route, such as `/dashboard/:widget`. Now, our `"."` links will, properly point to ourself _inclusive of the dynamic param value_ so behavior will break from it's corresponding usage in a `/dashboard/*` route.
+
+Even worse, consider a nested splat route configuration:
+
+```jsx
+<BrowserRouter>
+  <Routes>
+    <Route path="dashboard">
+      <Route path="*" element={<Dashboard />} />
+    </Route>
+  </Routes>
+</BrowserRouter>
+```
+
+Now, a `<Link to=".">` and a `<Link to="..">` inside the `Dashboard` component go to the same place! That is definitely not correct!
+
+Another common issue arose in Data Routers (and Remix) where any `<Form>` should post to it's own route `action` if you the user doesn't specify a form action:
+
+```jsx
+let router = createBrowserRouter({
+  path: "/dashboard",
+  children: [
+    {
+      path: "*",
+      action: dashboardAction,
+      Component() {
+        // ❌ This form is broken!  It throws a 405 error when it submits because
+        // it tries to submit to /dashboard (without the splat value) and the parent
+        // `/dashboard` route doesn't have an action
+        return <Form method="post">...</Form>;
+      },
+    },
+  ],
+});
+```
+
+This is just a compounded issue from the above because the default location for a `Form` to submit to is itself (`"."`) - and if we ignore the splat portion, that now resolves to the parent route.
+
+**The Solution**
+If you are leveraging this behavior, it's recommended to enable the future flag, move your splat to it's own route, and leverage `../` for any links to "sibling" pages:
+
+```jsx
+<BrowserRouter>
+  <Routes>
+    <Route path="dashboard">
+      <Route path="*" element={<Dashboard />} />
+    </Route>
+  </Routes>
+</BrowserRouter>
+
+function Dashboard() {
+  return (
+    <div>
+      <h2>Dashboard</h2>
+      <nav>
+        <Link to="..">Dashboard Home</Link>
+        <Link to="../team">Team</Link>
+        <Link to="../projects">Projects</Link>
+      </nav>
+
+      <Routes>
+        <Route path="/" element={<DashboardHome />} />
+        <Route path="team" element={<DashboardTeam />} />
+        <Route path="projects" element={<DashboardProjects />} />
+      </Router>
+    </div>
+  );
+}
+```
+
+This way, `.` means "the full current pathname for my route" in all cases (including static, dynamic, and splat routes) and `..` always means "my parents pathname".

docs/components/form.md

@@ -109,6 +109,8 @@ If you need to post to a different route, then add an action prop:
 
 - [Index Search Param][indexsearchparam] (index vs parent route disambiguation)
 
+<docs-info>Please see the [Splat Paths][relativesplatpath] section on the `useResolvedPath` docs for a note on the behavior of the `future.v7_relativeSplatPath` future flag for relative `useNavigate()` behavior within splat routes</docs-info>
+
 ## `method`
 
 This determines the [HTTP verb](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) to be used. The same as plain HTML [form method][htmlform-method], except it also supports "put", "patch", and "delete" in addition to "get" and "post". The default is "get".
@@ -394,3 +396,4 @@ You can access those values from the `request.url`
 [history-state]: https://developer.mozilla.org/en-US/docs/Web/API/History/state
 [use-view-transition-state]: ../hooks//use-view-transition-state
 [view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
+[relativesplatpath]: ../hooks/use-resolved-path#splat-paths

docs/components/link.md

@@ -63,6 +63,8 @@ A relative `<Link to>` value (that does not begin with `/`) resolves relative to
 
 <docs-info>`<Link to>` with a `..` behaves differently from a normal `<a href>` when the current URL ends with `/`. `<Link to>` ignores the trailing slash, and removes one URL segment for each `..`. But an `<a href>` value handles `..` differently when the current URL ends with `/` vs when it does not.</docs-info>
 
+<docs-info>Please see the [Splat Paths][relativesplatpath] section on the `useResolvedPath` docs for a note on the behavior of the `future.v7_relativeSplatPath` future flag for relative `<Link to>` behavior within splat routes</docs-info>
+
 ## `relative`
 
 By default, links are relative to the route hierarchy (`relative="route"`), so `..` will go up one `Route` level. Occasionally, you may find that you have matching URL patterns that do not make sense to be nested, and you'd prefer to use relative _path_ routing. You can opt into this behavior with `relative="path"`:
@@ -201,3 +203,4 @@ function ImageLink(to) {
 [view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
 [picking-a-router]: ../routers/picking-a-router
 [navlink]: ./nav-link
+[relativesplatpath]: ../hooks/use-resolved-path#splat-paths

docs/guides/api-development-strategy.md

@@ -63,12 +63,13 @@ const router = createBrowserRouter(routes, {
 });
 ```
 
-| Flag                                      | Description                                                           |
-| ----------------------------------------- | --------------------------------------------------------------------- |
-| `v7_fetcherPersist`                       | Delay active fetcher cleanup until they return to an `idle` state     |
-| `v7_normalizeFormMethod`                  | Normalize `useNavigation().formMethod` to be an uppercase HTTP Method |
-| [`v7_partialHydration`][partialhydration] | Support partial hydration for Server-rendered apps                    |
-| `v7_prependBasename`                      | Prepend the router basename to navigate/fetch paths                   |
+| Flag                                        | Description                                                           |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| `v7_fetcherPersist`                         | Delay active fetcher cleanup until they return to an `idle` state     |
+| `v7_normalizeFormMethod`                    | Normalize `useNavigation().formMethod` to be an uppercase HTTP Method |
+| [`v7_partialHydration`][partialhydration]   | Support partial hydration for Server-rendered apps                    |
+| `v7_prependBasename`                        | Prepend the router basename to navigate/fetch paths                   |
+| [`v7_relativeSplatPath`][relativesplatpath] | Fix buggy relative path resolution in splat routes                    |
 
 ### React Router Future Flags
 
@@ -96,3 +97,4 @@ These flags apply to both Data and non-Data Routers and are passed to the render
 [picking-a-router]: ../routers/picking-a-router
 [starttransition]: https://react.dev/reference/react/startTransition
 [partialhydration]: ../routers/create-browser-router#partial-hydration-data
+[relativesplatpath]: ../hooks/use-resolved-path#splat-paths

docs/hooks/use-href.md

@@ -18,8 +18,8 @@ declare function useHref(
 
 The `useHref` hook returns a URL that may be used to link to the given `to` location, even outside of React Router.
 
-> **Tip:**
->
-> You may be interested in taking a look at the source for the `<Link>`
-> component in `react-router-dom` to see how it uses `useHref` internally to
-> determine its own `href` value.
+<docs-info>You may be interested in taking a look at the source for the `<Link>` component in `react-router-dom` to see how it uses `useHref` internally to determine its own `href` value</docs-info>
+
+<docs-info>Please see the [Splat Paths][relativesplatpath] section on the `useResolvedPath` docs for a note on the behavior of the `future.v7_relativeSplatPath` future flag for relative `useHref()` behavior within splat routes</docs-info>
+
+[relativesplatpath]: ../hooks/use-resolved-path#splat-paths

docs/hooks/use-navigate.md

@@ -54,6 +54,8 @@ The `navigate` function has two signatures:
 - Either pass a `To` value (same type as `<Link to>`) with an optional second `options` argument (similar to the props you can pass to [`<Link>`][link]), or
 - Pass the delta you want to go in the history stack. For example, `navigate(-1)` is equivalent to hitting the back button
 
+<docs-info>Please see the [Splat Paths][relativesplatpath] section on the `useResolvedPath` docs for a note on the behavior of the `future.v7_relativeSplatPath` future flag for relative `useNavigate()` behavior within splat routes</docs-info>
+
 ## `options.replace`
 
 Specifying `replace: true` will cause the navigation to replace the current entry in the history stack instead of adding a new one.
@@ -119,3 +121,4 @@ The `unstable_viewTransition` option enables a [View Transition][view-transition
 [picking-a-router]: ../routers/picking-a-router
 [flush-sync]: https://react.dev/reference/react-dom/flushSync
 [start-transition]: https://react.dev/reference/react/startTransition
+[relativesplatpath]: ../hooks/use-resolved-path#splat-paths

docs/hooks/use-resolved-path.md

@@ -22,5 +22,64 @@ This is useful when building links from relative values. For example, check out
 
 See [resolvePath][resolvepath] for more information.
 
+## Splat Paths
+
+The original logic for `useResolvedPath` behaved differently for splat paths which in hindsight was incorrect/buggy behavior. This was fixed in [`6.19.0`][release-6.19.0] but it was determined that a large number of existing applications [relied on this behavior][revert-comment] so the fix was reverted in [`6.20.1`][release-6.20.1] and re-introduced in [`6.21.0`][release-6.21.0] behind a `future.v7_relativeSplatPath` [future flag][future-flag]. This will become the default behavior in React Router v7, so it is recommended to update your applications at your convenience to be better prepared for the eventual v7 upgrade.
+
+It should be noted that this is the foundation for all relative routing in React Router, so this applies to the following relative path code flows as well:
+
+- `<Link to>`
+- `useNavigate()`
+- `useHref()`
+- `<Form action>`
+- `useSubmit()`
+- Relative path `redirect` responses returned from loaders and actions
+
+### Behavior without the flag
+
+When this flag is not enabled, the default behavior is that when resolving relative paths inside of a [splat route (`*`)][splat], the splat portion of the path is ignored. So, given a route tree such as:
+
+```jsx
+<BrowserRouter>
+  <Routes>
+    <Route path="/dashboard/*" element={<Dashboard />} />
+  </Routes>
+</BrowserRouter>
+```
+
+If you are currently at URL `/dashboard/teams`, `useResolvedPath("projects")` inside the `Dashboard` component would resolve to `/dashboard/projects` because the "current" location we are relative to would be considered `/dashboard` _without the "teams" splat value_.
+
+This makes for a slight convenience in routing between "sibling" splat routes (`/dashboard/teams`, `/dashboard/projects`, etc.), however it causes other inconsistencies such as:
+
+- `useResolvedPath(".")` no longer resolves to the current location for that route, it actually resolved you "up" to `/dashboard` from `/dashboard/teams`
+- If you changed your route definition to use a dynamic parameter (`<Route path="/dashboard/:widget">`), then any resolved paths inside the `Dashboard` component would break since the dynamic param value is not ignored like the splat value
+
+And then it gets worse if you define the splat route as a child:
+
+```jsx
+<BrowserRouter>
+  <Routes>
+    <Route path="/dashboard">
+      <Route path="*" element={<Dashboard />} />
+    </Route>
+  </Routes>
+</BrowserRouter>
+```
+
+- Now, `useResolvedPath(".")` and `useResolvedPath("..")` resolve to the exact same path inside `<Dashboard />`
+- If you were using a Data Router and defined an `action` on the splat route, you'd get a 405 error on `<Form>` submissions because they (by default) submit to `"."` which would resolve to the parent `/dashboard` route which doesn't have an `action`.
+
+### Behavior with the flag
+
+When you enable the flag, this "bug" is fixed so that path resolution is consistent across all route types, `useResolvedPath(".")` always resolves to the current pathname for the contextual route. This includes any dynamic param or splat param values.
+
+If you want to navigate between "sibling" routes within a splat route, it is suggested you move your splat route to it's own child (`<Route path="*" element={<Dashboard />} />`) and use `useResolvedPath("../teams")` and `useResolvedPath("../projects")` parent-relative paths to navigate to sibling routes.
+
 [navlink]: ../components/nav-link
 [resolvepath]: ../utils/resolve-path
+[release-6.19.0]: https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#v6190
+[release-6.20.1]: https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#v6201
+[release-6.21.0]: https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#v6210
+[revert-comment]: https://github.com/remix-run/react-router/issues/11052#issuecomment-1836589329
+[future-flag]: ../guides/api-development-strategy
+[splat]: ../route/route#splats

docs/hooks/use-submit.md

@@ -150,6 +150,8 @@ submit(null, {
 <Form action="/logout" method="post" />;
 ```
 
+<docs-info>Please see the [Splat Paths][relativesplatpath] section on the `useResolvedPath` docs for a note on the behavior of the `future.v7_relativeSplatPath` future flag for relative `useSubmit()` `action` behavior within splat routes</docs-info>
+
 Because submissions are navigations, the options may also contain the other navigation related props from [`<Form>`][form] such as:
 
 - `fetcherKey`
@@ -170,3 +172,4 @@ The `unstable_flushSync` option tells React Router DOM to wrap the initial state
 [form]: ../components/form
 [flush-sync]: https://react.dev/reference/react-dom/flushSync
 [start-transition]: https://react.dev/reference/react/startTransition
+[relativesplatpath]: ../hooks/use-resolved-path#splat-paths

package.json

@@ -110,19 +110,19 @@
   },
   "filesize": {
     "packages/router/dist/router.umd.min.js": {
-      "none": "49.8 kB"
+      "none": "50.1 kB"
     },
     "packages/react-router/dist/react-router.production.min.js": {
-      "none": "14.5 kB"
+      "none": "14.6 kB"
     },
     "packages/react-router/dist/umd/react-router.production.min.js": {
-      "none": "16.9 kB"
+      "none": "17.0 kB"
     },
     "packages/react-router-dom/dist/react-router-dom.production.min.js": {
-      "none": "16.7 kB"
+      "none": "16.8 kB"
     },
     "packages/react-router-dom/dist/umd/react-router-dom.production.min.js": {
-      "none": "22.9 kB"
+      "none": "23.0 kB"
     }
   }
 }

packages/react-router-dom-v5-compat/index.ts

@@ -59,6 +59,7 @@ export type {
   FormEncType,
   FormMethod,
   FormProps,
+  FutureConfig,
   GetScrollRestorationKeyFunction,
   Hash,
   HashRouterProps,

packages/react-router-dom/index.tsx

@@ -104,6 +104,7 @@ export type {
   DataRouteObject,
   ErrorResponse,
   Fetcher,
+  FutureConfig,
   Hash,
   IndexRouteObject,
   IndexRouteProps,
@@ -666,6 +667,9 @@ export function RouterProvider({
       navigator,
       static: false,
       basename,
+      future: {
+        v7_relativeSplatPath: router.future.v7_relativeSplatPath,
+      },
     }),
     [router, navigator, basename]
   );
@@ -764,6 +768,7 @@ export function BrowserRouter({
       location={state.location}
       navigationType={state.action}
       navigator={history}
+      future={future}
     />
   );
 }
@@ -814,6 +819,7 @@ export function HashRouter({
       location={state.location}
       navigationType={state.action}
       navigator={history}
+      future={future}
     />
   );
 }
@@ -860,6 +866,7 @@ function HistoryRouter({
       location={state.location}
       navigationType={state.action}
       navigator={history}
+      future={future}
     />
   );
 }
@@ -1558,10 +1565,8 @@ export function useFormAction(
   // object referenced by useMemo inside useResolvedPath
   let path = { ...useResolvedPath(action ? action : ".", { relative }) };
 
-  // Previously we set the default action to ".". The problem with this is that
-  // `useResolvedPath(".")` excludes search params of the resolved URL. This is
-  // the intended behavior of when "." is specifically provided as
-  // the form action, but inconsistent w/ browsers when the action is omitted.
+  // If no action was specified, browsers will persist current search params
+  // when determining the path, so match that behavior
   // https://github.com/remix-run/remix/issues/927
   let location = useLocation();
   if (action == null) {