feat: added reloadDocument to <Link> and <NavLink> (#8283)

* feat: added forceDocument to `<Link>`

* renamed to reloadDocument

* chore(docs): added docs on reloadDocument

* chore(docs): typos

Co-authored-by: Ryan Florence <[email protected]>

Author: 2 people

docs/api.md

@@ -252,17 +252,17 @@ interface LinkProps
     "href"
   > {
   replace?: boolean;
-  state?: State;
+  state?: any;
   to: To;
+  reloadDocument?: boolean;
 }
 
-type State = object | null;
 type To = Partial<Location> | string;
 ```
 
 </details>
 
-A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it. In `react-router-dom`, a `<Link>` renders an accessible `<a>` element with a real `href` that points to the resource it's linking to. This means that things like right-clicking a `<Link>` work as you'd expect.
+A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it. In `react-router-dom`, a `<Link>` renders an accessible `<a>` element with a real `href` that points to the resource it's linking to. This means that things like right-clicking a `<Link>` work as you'd expect. You can use `<Link reloadDocument>` to skip client side routing and let the browser handle the transition normally (as if it were an `<a href>`).
 
 ```tsx
 import * as React from "react";

packages/react-router-dom/__tests__/link-click-test.tsx

@@ -3,15 +3,15 @@ import * as ReactDOM from "react-dom";
 import { act } from "react-dom/test-utils";
 import { MemoryRouter, Routes, Route, Link } from "react-router-dom";
 
-function click(anchor: HTMLAnchorElement, eventInit?: MouseEventInit): void {
-  anchor.dispatchEvent(
-    new MouseEvent("click", {
-      view: window,
-      bubbles: true,
-      cancelable: true,
-      ...eventInit
-    })
-  );
+function click(anchor: HTMLAnchorElement, eventInit?: MouseEventInit) {
+  let event = new MouseEvent("click", {
+    view: window,
+    bubbles: true,
+    cancelable: true,
+    ...eventInit
+  });
+  anchor.dispatchEvent(event);
+  return event;
 }
 
 describe("A <Link> click", () => {
@@ -51,15 +51,54 @@ describe("A <Link> click", () => {
     let anchor = node.querySelector("a");
     expect(anchor).not.toBeNull();
 
+    let event: MouseEvent;
     act(() => {
-      click(anchor);
+      event = click(anchor);
     });
 
+    expect(event.defaultPrevented).toBe(true);
     let h1 = node.querySelector("h1");
     expect(h1).not.toBeNull();
     expect(h1?.textContent).toEqual("About");
   });
 
+  describe("when reloadDocument is specified", () => {
+    it("does not prevent default", () => {
+      function Home() {
+        return (
+          <div>
+            <h1>Home</h1>
+            <Link reloadDocument to="../about">
+              About
+            </Link>
+          </div>
+        );
+      }
+
+      act(() => {
+        ReactDOM.render(
+          <MemoryRouter initialEntries={["/home"]}>
+            <Routes>
+              <Route path="home" element={<Home />} />
+              <Route path="about" element={<h1>About</h1>} />
+            </Routes>
+          </MemoryRouter>,
+          node
+        );
+      });
+
+      let anchor = node.querySelector("a");
+      expect(anchor).not.toBeNull();
+
+      let event: MouseEvent;
+      act(() => {
+        event = click(anchor);
+      });
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+  });
+
   describe("when preventDefault is used on the click handler", () => {
     it("stays on the same page", () => {
       function Home() {

packages/react-router-dom/index.tsx

@@ -200,6 +200,7 @@ function isModifiedEvent(event: React.MouseEvent) {
 
 export interface LinkProps
   extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  reloadDocument?: boolean;
   replace?: boolean;
   state?: any;
   to: To;
@@ -210,7 +211,7 @@ export interface LinkProps
  */
 export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
   function LinkWithRef(
-    { onClick, replace = false, state, target, to, ...rest },
+    { onClick, reloadDocument, replace = false, state, target, to, ...rest },
     ref
   ) {
     let href = useHref(to);
@@ -219,7 +220,7 @@ export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
       event: React.MouseEvent<HTMLAnchorElement, MouseEvent>
     ) {
       if (onClick) onClick(event);
-      if (!event.defaultPrevented) {
+      if (!event.defaultPrevented && !reloadDocument) {
         internalOnClick(event);
       }
     }