json({ ok: true })}
+ element={
+ <>
+ Three
+
+
+ }
+ />
+ Four} />
+
+ )
+);
+
+if (import.meta.hot) {
+ import.meta.hot.dispose(() => router.dispose());
+}
+
+export default function App() {
+ return ;
+}
+
+function Layout() {
+ let [historyIndex, setHistoryIndex] = React.useState(
+ window.history.state?.idx
+ );
+ let location = useLocation();
+
+ // Expose the underlying history index in the UI for debugging
+ React.useEffect(() => {
+ setHistoryIndex(window.history.state?.idx);
+ }, [location]);
+
+ // Give us meaningful document titles for popping back/forward more than 1 entry
+ React.useEffect(() => {
+ document.title = location.pathname;
+ }, [location]);
+
+ return (
+ <>
+ Navigation Blocking Example
+
+
+ Current location (index): {location.pathname} ({historyIndex})
+
+
+
+ );
+}
+
+function ImportantForm() {
+ let [value, setValue] = React.useState("");
+ let isBlocked = value !== "";
+ let blocker = useBlocker(isBlocked);
+
+ // Reset the blocker if the user cleans the form
+ React.useEffect(() => {
+ if (blocker.state === "blocked" && !isBlocked) {
+ blocker.reset();
+ }
+ }, [blocker, isBlocked]);
+
+ return (
+ <>
+
+ Is the form dirty?{" "}
+ {isBlocked ? (
+ Yes
+ ) : (
+ No
+ )}
+
+
+
+
+ {blocker ? : null}
+
+ );
+}
+
+function ConfirmNavigation({ blocker }: { blocker: Blocker }) {
+ if (blocker.state === "blocked") {
+ return (
+ <>
+
+ Blocked the last navigation to {blocker.location.pathname}
+
+
+
+
+ );
+ }
+
+ if (blocker.state === "proceeding") {
+ return (
+ Proceeding through blocked navigation
+ );
+ }
+
+ return Blocker is currently unblocked
;
+}
diff --git a/examples/navigation-blocking/src/main.tsx b/examples/navigation-blocking/src/main.tsx
new file mode 100644
index 0000000000..32a669c16c
--- /dev/null
+++ b/examples/navigation-blocking/src/main.tsx
@@ -0,0 +1,9 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./app";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+
+
+
+);
diff --git a/examples/navigation-blocking/src/vite-env.d.ts b/examples/navigation-blocking/src/vite-env.d.ts
new file mode 100644
index 0000000000..11f02fe2a0
--- /dev/null
+++ b/examples/navigation-blocking/src/vite-env.d.ts
@@ -0,0 +1 @@
+///
diff --git a/examples/navigation-blocking/tsconfig.json b/examples/navigation-blocking/tsconfig.json
new file mode 100644
index 0000000000..8bdaabfe5d
--- /dev/null
+++ b/examples/navigation-blocking/tsconfig.json
@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "baseUrl": ".",
+ "target": "ESNext",
+ "lib": ["DOM", "DOM.Iterable", "ESNext"],
+ "allowJs": false,
+ "skipLibCheck": true,
+ "esModuleInterop": false,
+ "allowSyntheticDefaultImports": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "module": "ESNext",
+ "moduleResolution": "Node",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "noEmit": true,
+ "jsx": "react",
+ "importsNotUsedAsValues": "error"
+ },
+ "include": ["./src"]
+}
diff --git a/examples/navigation-blocking/vite.config.ts b/examples/navigation-blocking/vite.config.ts
new file mode 100644
index 0000000000..b77eb48a30
--- /dev/null
+++ b/examples/navigation-blocking/vite.config.ts
@@ -0,0 +1,36 @@
+import * as path from "path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import rollupReplace from "@rollup/plugin-replace";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+ plugins: [
+ rollupReplace({
+ preventAssignment: true,
+ values: {
+ __DEV__: JSON.stringify(true),
+ "process.env.NODE_ENV": JSON.stringify("development"),
+ },
+ }),
+ react(),
+ ],
+ resolve: process.env.USE_SOURCE
+ ? {
+ alias: {
+ "@remix-run/router": path.resolve(
+ __dirname,
+ "../../packages/router/index.ts"
+ ),
+ "react-router": path.resolve(
+ __dirname,
+ "../../packages/react-router/index.ts"
+ ),
+ "react-router-dom": path.resolve(
+ __dirname,
+ "../../packages/react-router-dom/index.tsx"
+ ),
+ },
+ }
+ : {},
+});
diff --git a/package.json b/package.json
index 037d859131..3cb029f761 100644
--- a/package.json
+++ b/package.json
@@ -25,6 +25,7 @@
"release": "changeset publish",
"size": "filesize",
"test": "jest",
+ "test:inspect": "node --inspect-brk ./node_modules/.bin/jest",
"changeset": "changeset",
"version": "changeset version",
"postversion": "node scripts/postversion.mjs",
@@ -108,10 +109,10 @@
},
"filesize": {
"packages/router/dist/router.umd.min.js": {
- "none": "38.5 kB"
+ "none": "41 kB"
},
"packages/react-router/dist/react-router.production.min.js": {
- "none": "12.5 kB"
+ "none": "13 kB"
},
"packages/react-router/dist/umd/react-router.production.min.js": {
"none": "15 kB"
diff --git a/packages/react-router-dom/__tests__/use-blocker-test.tsx b/packages/react-router-dom/__tests__/use-blocker-test.tsx
new file mode 100644
index 0000000000..417540729c
--- /dev/null
+++ b/packages/react-router-dom/__tests__/use-blocker-test.tsx
@@ -0,0 +1,1004 @@
+import * as React from "react";
+import * as ReactDOM from "react-dom/client";
+import { act } from "react-dom/test-utils";
+import type { unstable_Blocker as Blocker, RouteObject } from "../index";
+import {
+ createMemoryRouter,
+ json,
+ NavLink,
+ Outlet,
+ RouterProvider,
+ unstable_useBlocker as useBlocker,
+ useNavigate,
+} from "../index";
+
+type Router = ReturnType;
+
+const LOADER_LATENCY_MS = 100;
+
+async function slowLoader() {
+ await sleep(LOADER_LATENCY_MS);
+ return json(null);
+}
+
+describe("navigation blocking with useBlocker", () => {
+ let node: HTMLDivElement;
+ let router: Router;
+ let blocker: Blocker | null = null;
+ let root: ReactDOM.Root;
+
+ beforeEach(() => {
+ node = document.createElement("div");
+ document.body.appendChild(node);
+ });
+
+ afterEach(() => {
+ document.body.removeChild(node);
+ node = null!;
+ });
+
+ it("initializes an 'unblocked' blocker", async () => {
+ let initialEntries = ["/"];
+ let routes: RouteObject[] = [
+ {
+ path: "/",
+ element: React.createElement(() => {
+ let b = useBlocker(false);
+ blocker = b;
+ return null;
+ }),
+ },
+ ];
+ router = createMemoryRouter(routes, { initialEntries });
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ });
+ act(() => {
+ root.unmount();
+ });
+ });
+
+ describe("on navigation", () => {
+ describe("blocker returns false", () => {
+ beforeEach(() => {
+ let initialEntries = ["/"];
+ let initialIndex = 0;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(false);
+ blocker = b;
+ return (
+
+ Home
+ About
+
+
+ );
+ }),
+ children: [
+ {
+ path: "/",
+ element: Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("navigates", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("About");
+ });
+
+ it("gets an 'unblocked' blocker after navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("gets an 'unblocked' blocker after navigation completes", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+ });
+
+ describe("blocker returns true", () => {
+ beforeEach(() => {
+ let initialEntries = ["/"];
+ let initialIndex = 0;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(true);
+ blocker = b;
+ return (
+
+ Home
+ About
+
+
+ );
+ }),
+ children: [
+ {
+ path: "/",
+ element: Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("does not navigate", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).not.toBe("About");
+ });
+
+ it("gets a 'blocked' blocker after navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ expect(blocker).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets a 'blocked' blocker after navigation promise resolves", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+ });
+
+ describe("exiting from blocked state", () => {
+ beforeEach(() => {
+ let initialEntries = ["/"];
+ let initialIndex = 0;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(true);
+ blocker = b;
+ return (
+
+
Home
+
About
+ {b.state === "blocked" && (
+
+
+
+
+ )}
+
+
Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("gets a 'proceeding' blocker after proceeding navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ act(() => {
+ click(node.querySelector("[data-action='proceed']"));
+ });
+ expect(blocker).toEqual({
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets an 'unblocked' blocker after proceeding navigation completes", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='proceed']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("navigates after proceeding navigation completes", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='proceed']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("About");
+ });
+
+ it("gets an 'unblocked' blocker after resetting navigation", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ act(() => {
+ click(node.querySelector("[data-action='reset']"));
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("stays at current location after resetting", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='reset']"));
+ // wait for '/about' loader so we catch failure if navigation proceeds
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("Home");
+ });
+ });
+ });
+
+ describe("on navigation", () => {
+ describe("blocker returns false", () => {
+ beforeEach(() => {
+ let initialEntries = ["/"];
+ let initialIndex = 0;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(false);
+ blocker = b;
+ return (
+
+
+ Home
+
+
+ About
+
+
+
+ );
+ }),
+ children: [
+ {
+ path: "/",
+ element: Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("navigates", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("About");
+ });
+
+ it("gets an 'unblocked' blocker after navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("gets an 'unblocked' blocker after navigation completes", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+ });
+
+ describe("blocker returns true", () => {
+ beforeEach(() => {
+ let initialEntries = ["/"];
+ let initialIndex = 0;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(true);
+ blocker = b;
+ return (
+
+
+ Home
+
+
+ About
+
+
+
+ );
+ }),
+ children: [
+ {
+ path: "/",
+ element: Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("does not navigate", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).not.toBe("About");
+ });
+
+ it("gets a 'blocked' blocker after navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ expect(blocker).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets a 'blocked' blocker after navigation promise resolves", async () => {
+ await act(async () => {
+ click(node.querySelector("a[href='/about']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+ });
+
+ describe("exiting from blocked state", () => {
+ beforeEach(() => {
+ let initialEntries = ["/"];
+ let initialIndex = 0;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(true);
+ blocker = b;
+ return (
+
+
+ Home
+
+
+ About
+
+ {b.state === "blocked" && (
+
+
+
+
+ )}
+
+
Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("gets a 'proceeding' blocker after proceeding navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ act(() => {
+ click(node.querySelector("[data-action='proceed']"));
+ });
+ expect(blocker).toEqual({
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets an 'unblocked' blocker after proceeding navigation completes", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='proceed']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("navigates after proceeding navigation completes", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='proceed']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("About");
+ });
+
+ it("gets an 'unblocked' blocker after resetting navigation", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ act(() => {
+ click(node.querySelector("[data-action='reset']"));
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("stays at current location after resetting", async () => {
+ act(() => {
+ click(node.querySelector("a[href='/about']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='reset']"));
+ // wait for '/about' loader so we catch failure if navigation proceeds
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("Home");
+ });
+ });
+ });
+
+ describe("on POP navigation", () => {
+ describe("blocker returns false", () => {
+ beforeEach(() => {
+ let initialEntries = ["/", "/about", "/contact"];
+ let initialIndex = 2;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(false);
+ let navigate = useNavigate();
+ blocker = b;
+ return (
+
+
+ Home
+
+
+ About
+
+
+
+
+ );
+ }),
+ children: [
+ {
+ path: "/",
+ element: Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ {
+ path: "/contact",
+ element: Contact
,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("navigates", async () => {
+ await act(async () => {
+ click(node.querySelector("[data-action='back']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("About");
+ });
+
+ it("gets an 'unblocked' blocker after navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("[data-action='back']"));
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("gets an 'unblocked' blocker after navigation completes", async () => {
+ await act(async () => {
+ click(node.querySelector("[data-action='back']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+ });
+
+ describe("blocker returns true", () => {
+ beforeEach(() => {
+ let initialEntries = ["/", "/about", "/contact"];
+ let initialIndex = 2;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(true);
+ let navigate = useNavigate();
+ blocker = b;
+ return (
+
+
+ Home
+
+
+ About
+
+
+
+
+ );
+ }),
+ children: [
+ {
+ path: "/",
+ element: Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ {
+ path: "/contact",
+ element: Contact
,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("does not navigate", async () => {
+ await act(async () => {
+ click(node.querySelector("[data-action='back']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).not.toBe("About");
+ });
+
+ it("gets a 'blocked' blocker after navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("[data-action='back']"));
+ });
+ expect(blocker).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets a 'blocked' blocker after navigation promise resolves", async () => {
+ await act(async () => {
+ click(node.querySelector("[data-action='back']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+ });
+
+ describe("exiting from blocked state", () => {
+ beforeEach(() => {
+ let initialEntries = ["/", "/about", "/contact"];
+ let initialIndex = 2;
+ router = createMemoryRouter(
+ [
+ {
+ element: React.createElement(() => {
+ let b = useBlocker(true);
+ let navigate = useNavigate();
+ blocker = b;
+ return (
+
+
+ Home
+
+
+ About
+
+
+ {b.state === "blocked" && (
+
+
+
+
+ )}
+
+
Home
,
+ },
+ {
+ path: "/about",
+ element: About
,
+ loader: slowLoader,
+ },
+ {
+ path: "/contact",
+ element: Contact
,
+ },
+ ],
+ },
+ ],
+ {
+ initialEntries,
+ initialIndex,
+ }
+ );
+ act(() => {
+ root = ReactDOM.createRoot(node);
+ root.render();
+ });
+ });
+
+ afterEach(() => {
+ act(() => root.unmount());
+ });
+
+ it("gets a 'proceeding' blocker after proceeding navigation starts", async () => {
+ act(() => {
+ click(node.querySelector("[data-action='back']"));
+ });
+ act(() => {
+ click(node.querySelector("[data-action='proceed']"));
+ });
+ expect(blocker).toEqual({
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets an 'unblocked' blocker after proceeding navigation completes", async () => {
+ act(() => {
+ click(node.querySelector("[data-action='back']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='proceed']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("navigates after proceeding navigation completes", async () => {
+ act(() => {
+ click(node.querySelector("[data-action='back']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='proceed']"));
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("About");
+ });
+
+ it("gets an 'unblocked' blocker after resetting navigation", async () => {
+ act(() => {
+ click(node.querySelector("[data-action='back']"));
+ });
+ act(() => {
+ click(node.querySelector("[data-action='reset']"));
+ });
+ expect(blocker).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("stays at current location after resetting", async () => {
+ act(() => {
+ click(node.querySelector("[data-action='back']"));
+ });
+ await act(async () => {
+ click(node.querySelector("[data-action='reset']"));
+ // wait for '/about' loader so we catch failure if navigation proceeds
+ await sleep(LOADER_LATENCY_MS);
+ });
+ let h1 = node.querySelector("h1");
+ expect(h1?.textContent).toBe("Contact");
+ });
+ });
+ });
+});
+
+function sleep(n: number = 500) {
+ return new Promise((r) => setTimeout(r, n));
+}
+
+function click(target: EventTarget | null | undefined) {
+ target?.dispatchEvent(
+ new MouseEvent("click", {
+ view: window,
+ bubbles: true,
+ cancelable: true,
+ })
+ );
+}
diff --git a/packages/react-router-dom/index.tsx b/packages/react-router-dom/index.tsx
index cf0fd14240..f5a1dd4590 100644
--- a/packages/react-router-dom/index.tsx
+++ b/packages/react-router-dom/index.tsx
@@ -76,6 +76,8 @@ export type {
ActionFunction,
ActionFunctionArgs,
AwaitProps,
+ unstable_Blocker,
+ unstable_BlockerFunction,
DataRouteMatch,
DataRouteObject,
Fetcher,
@@ -142,6 +144,7 @@ export {
useActionData,
useAsyncError,
useAsyncValue,
+ unstable_useBlocker,
useHref,
useInRouterContext,
useLoaderData,
@@ -1185,14 +1188,17 @@ function useScrollRestoration({
* `React.useCallback()`.
*/
export function useBeforeUnload(
- callback: (event: BeforeUnloadEvent) => any
+ callback: (event: BeforeUnloadEvent) => any,
+ options?: { capture?: boolean }
): void {
+ let { capture } = options || {};
React.useEffect(() => {
- window.addEventListener("beforeunload", callback);
+ let opts = capture != null ? { capture } : undefined;
+ window.addEventListener("beforeunload", callback, opts);
return () => {
- window.removeEventListener("beforeunload", callback);
+ window.removeEventListener("beforeunload", callback, opts);
};
- }, [callback]);
+ }, [callback, capture]);
}
//#endregion
diff --git a/packages/react-router-dom/server.tsx b/packages/react-router-dom/server.tsx
index a8ac8cb10c..3ace651b43 100644
--- a/packages/react-router-dom/server.tsx
+++ b/packages/react-router-dom/server.tsx
@@ -263,6 +263,7 @@ export function createStaticRouter(
preventScrollReset: false,
revalidation: "idle" as RevalidationState,
fetchers: new Map(),
+ blockers: new Map(),
};
},
get routes() {
@@ -297,6 +298,12 @@ export function createStaticRouter(
dispose() {
throw msg("dispose");
},
+ getBlocker() {
+ throw msg("getBlocker");
+ },
+ deleteBlocker() {
+ throw msg("deleteBlocker");
+ },
_internalFetchControllers: new Map(),
_internalActiveDeferreds: new Map(),
};
diff --git a/packages/react-router-native/index.tsx b/packages/react-router-native/index.tsx
index 5d66fccb83..d89e3fba19 100644
--- a/packages/react-router-native/index.tsx
+++ b/packages/react-router-native/index.tsx
@@ -23,6 +23,8 @@ export type {
ActionFunction,
ActionFunctionArgs,
AwaitProps,
+ unstable_Blocker,
+ unstable_BlockerFunction,
DataRouteMatch,
DataRouteObject,
Fetcher,
@@ -89,6 +91,7 @@ export {
useActionData,
useAsyncError,
useAsyncValue,
+ unstable_useBlocker,
useHref,
useInRouterContext,
useLoaderData,
diff --git a/packages/react-router/index.ts b/packages/react-router/index.ts
index 2af02fef6c..3d55ed2e22 100644
--- a/packages/react-router/index.ts
+++ b/packages/react-router/index.ts
@@ -1,6 +1,8 @@
import type {
ActionFunction,
ActionFunctionArgs,
+ Blocker,
+ BlockerFunction,
Fetcher,
HydrationState,
JsonFunction,
@@ -82,6 +84,7 @@ import {
} from "./lib/context";
import type { NavigateFunction } from "./lib/hooks";
import {
+ useBlocker,
useHref,
useInRouterContext,
useLocation,
@@ -114,6 +117,8 @@ export type {
ActionFunction,
ActionFunctionArgs,
AwaitProps,
+ Blocker as unstable_Blocker,
+ BlockerFunction as unstable_BlockerFunction,
DataRouteMatch,
DataRouteObject,
Fetcher,
@@ -179,6 +184,7 @@ export {
useActionData,
useAsyncError,
useAsyncValue,
+ useBlocker as unstable_useBlocker,
useHref,
useInRouterContext,
useLoaderData,
diff --git a/packages/react-router/lib/hooks.tsx b/packages/react-router/lib/hooks.tsx
index 96ff63e747..eb4bc220a8 100644
--- a/packages/react-router/lib/hooks.tsx
+++ b/packages/react-router/lib/hooks.tsx
@@ -1,5 +1,7 @@
import * as React from "react";
import type {
+ Blocker,
+ BlockerFunction,
Location,
ParamParseKey,
Params,
@@ -650,6 +652,7 @@ export function _renderMatches(
}
enum DataRouterHook {
+ UseBlocker = "useBlocker",
UseRevalidator = "useRevalidator",
}
@@ -818,6 +821,36 @@ export function useAsyncError(): unknown {
return value?._error;
}
+// useBlocker() is a singleton for now since we don't have any compelling use
+// cases for multi-blocker yet
+let blockerKey = "blocker-singleton";
+
+/**
+ * Allow the application to block navigations within the SPA and present the
+ * user a confirmation dialog to confirm the navigation. Mostly used to avoid
+ * using half-filled form data. This does not handle hard-reloads or
+ * cross-origin navigations.
+ */
+export function useBlocker(shouldBlock: boolean | BlockerFunction): Blocker {
+ let { router } = useDataRouterContext(DataRouterHook.UseBlocker);
+
+ let blockerFunction = React.useCallback(
+ (args) => {
+ return typeof shouldBlock === "function"
+ ? !!shouldBlock(args)
+ : !!shouldBlock;
+ },
+ [shouldBlock]
+ );
+
+ let blocker = router.getBlocker(blockerKey, blockerFunction);
+
+ // Cleanup on unmount
+ React.useEffect(() => () => router.deleteBlocker(blockerKey), [router]);
+
+ return blocker;
+}
+
const alreadyWarned: Record = {};
function warningOnce(key: string, cond: boolean, message: string) {
diff --git a/packages/router/__tests__/TestSequences/GoBack.ts b/packages/router/__tests__/TestSequences/GoBack.ts
index d7009441eb..03a6711818 100644
--- a/packages/router/__tests__/TestSequences/GoBack.ts
+++ b/packages/router/__tests__/TestSequences/GoBack.ts
@@ -31,6 +31,7 @@ export default async function GoBack(history: History) {
});
expect(spy).toHaveBeenCalledWith({
action: "POP",
+ delta: expect.any(Number),
location: {
hash: "",
key: expect.any(String),
diff --git a/packages/router/__tests__/TestSequences/GoForward.ts b/packages/router/__tests__/TestSequences/GoForward.ts
index 5949524b26..ccc9f09c3a 100644
--- a/packages/router/__tests__/TestSequences/GoForward.ts
+++ b/packages/router/__tests__/TestSequences/GoForward.ts
@@ -31,6 +31,7 @@ export default async function GoForward(history: History) {
});
expect(spy).toHaveBeenCalledWith({
action: "POP",
+ delta: expect.any(Number),
location: {
hash: "",
key: expect.any(String),
@@ -58,6 +59,7 @@ export default async function GoForward(history: History) {
});
expect(spy).toHaveBeenCalledWith({
action: "POP",
+ delta: expect.any(Number),
location: {
hash: "",
key: expect.any(String),
diff --git a/packages/router/__tests__/navigation-blocking-test.ts b/packages/router/__tests__/navigation-blocking-test.ts
new file mode 100644
index 0000000000..e0fdc616f2
--- /dev/null
+++ b/packages/router/__tests__/navigation-blocking-test.ts
@@ -0,0 +1,493 @@
+import type { Router } from "../index";
+import { createMemoryHistory, createRouter } from "../index";
+
+const LOADER_LATENCY_MS = 100;
+const routes = [
+ { path: "/" },
+ {
+ path: "/about",
+ loader: () => sleep(LOADER_LATENCY_MS),
+ },
+ { path: "/contact" },
+ { path: "/help" },
+];
+
+describe("navigation blocking", () => {
+ let router: Router;
+ it("initializes an 'unblocked' blocker", () => {
+ router = createRouter({
+ history: createMemoryHistory({
+ initialEntries: ["/"],
+ initialIndex: 0,
+ }),
+ routes,
+ });
+ router.initialize();
+
+ let fn = () => true;
+ router.getBlocker("KEY", fn);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ describe("on history push", () => {
+ let initialEntries = ["/", "/about"];
+ let initialIndex = 0;
+ beforeEach(() => {
+ router = createRouter({
+ history: createMemoryHistory({
+ initialEntries,
+ initialIndex,
+ }),
+ routes,
+ });
+ router.initialize();
+ });
+
+ describe("blocker returns false", () => {
+ let fn = () => false;
+ it("navigates", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ expect(router.state.location.pathname).toBe("/about");
+ });
+
+ it("gets an 'unblocked' blocker after navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ router.navigate("/about");
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("gets an 'unblocked' blocker after navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+ });
+
+ describe("blocker returns true", () => {
+ let fn = () => true;
+
+ it("does not navigate", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ expect(router.state.location.pathname).toBe(
+ initialEntries[initialIndex]
+ );
+ });
+
+ it("gets a 'blocked' blocker after navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ router.navigate("/about");
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets a 'blocked' blocker after navigation promise resolves", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+ });
+
+ describe("proceeds from blocked state", () => {
+ let fn = () => true;
+ it("gets a 'proceeding' blocker after proceeding navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ router.getBlocker("KEY", fn).proceed?.();
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets an 'unblocked' blocker after proceeding navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ router.getBlocker("KEY", fn).proceed?.();
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("navigates after proceeding navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ router.getBlocker("KEY", fn).proceed?.();
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.state.location.pathname).toBe("/about");
+ });
+ });
+
+ describe("resets from blocked state", () => {
+ let fn = () => true;
+ it("gets an 'unblocked' blocker after resetting navigation", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about");
+ router.getBlocker("KEY", fn).reset?.();
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("stays at current location after resetting", async () => {
+ router.getBlocker("KEY", fn);
+ let pathnameBeforeNavigation = router.state.location.pathname;
+ await router.navigate("/about");
+ router.getBlocker("KEY", fn).reset?.();
+
+ // wait for '/about' loader so we catch failure if navigation proceeds
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.state.location.pathname).toBe(pathnameBeforeNavigation);
+ });
+ });
+ });
+
+ describe("on history replace", () => {
+ let initialEntries = ["/", "/about"];
+ let initialIndex = 0;
+ beforeEach(() => {
+ router = createRouter({
+ history: createMemoryHistory({
+ initialEntries,
+ initialIndex,
+ }),
+ routes,
+ });
+ router.initialize();
+ });
+
+ describe("blocker returns false", () => {
+ let fn = () => false;
+ it("navigates", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ expect(router.state.location.pathname).toBe("/about");
+ });
+
+ it("gets an 'unblocked' blocker after navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ router.navigate("/about", { replace: true });
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("gets an 'unblocked' blocker after navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+ });
+
+ describe("blocker returns true", () => {
+ let fn = () => true;
+
+ it("does not navigate", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ expect(router.state.location.pathname).toBe(
+ initialEntries[initialIndex]
+ );
+ });
+
+ it("gets a 'blocked' blocker after navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ router.navigate("/about", { replace: true });
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets a 'blocked' blocker after navigation promise resolves", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+ });
+
+ describe("proceeds from blocked state", () => {
+ let fn = () => true;
+ it("gets a 'proceeding' blocker after proceeding navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ router.getBlocker("KEY", fn).proceed?.();
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets an 'unblocked' blocker after proceeding navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ router.getBlocker("KEY", fn).proceed?.();
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("navigates after proceeding navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ router.getBlocker("KEY", fn).proceed?.();
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.state.location.pathname).toBe("/about");
+ });
+
+ it("replaces the current history entry after proceeding completes", async () => {
+ router.getBlocker("KEY", fn);
+ let historyLengthBeforeNavigation = window.history.length;
+ await router.navigate("/about", { replace: true });
+ router.getBlocker("KEY", fn).proceed?.();
+ await sleep(LOADER_LATENCY_MS);
+ expect(window.history.length).toBe(historyLengthBeforeNavigation);
+ });
+ });
+
+ describe("resets from blocked state", () => {
+ let fn = () => true;
+ it("gets an 'unblocked' blocker after resetting navigation", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate("/about", { replace: true });
+ router.getBlocker("KEY", fn).reset?.();
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined
+ });
+ });
+
+ it("stays at current location after resetting", async () => {
+ router.getBlocker("KEY", fn);
+ let pathnameBeforeNavigation = router.state.location.pathname;
+ await router.navigate("/about", { replace: true });
+ router.getBlocker("KEY", fn).reset?.();
+
+ // wait for '/about' loader so we catch failure if navigation proceeds
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.state.location.pathname).toBe(pathnameBeforeNavigation);
+ });
+ });
+ });
+
+ describe("on history pop", () => {
+ let initialEntries = ["/", "/about", "/contact", "/help"];
+ let initialIndex = 1;
+ beforeEach(() => {
+ router = createRouter({
+ history: createMemoryHistory({
+ initialEntries,
+ initialIndex,
+ }),
+ routes,
+ });
+ router.initialize();
+ });
+
+ describe("blocker returns false", () => {
+ let fn = () => false;
+ it("navigates", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ expect(router.state.location.pathname).toBe(
+ initialEntries[initialIndex - 1]
+ );
+ });
+
+ it("gets an 'unblocked' blocker after navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ router.navigate(-1);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("gets an 'unblocked' blocker after navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+ });
+
+ describe("blocker returns true", () => {
+ let fn = () => true;
+
+ it("does not navigate", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ expect(router.state.location.pathname).toBe(
+ initialEntries[initialIndex]
+ );
+ });
+
+ it("gets a 'blocked' blocker after navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ router.navigate(-1);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets a 'blocked' blocker after navigation promise resolves", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "blocked",
+ proceed: expect.any(Function),
+ reset: expect.any(Function),
+ location: expect.any(Object),
+ });
+ });
+ });
+
+ describe("proceeds from blocked state", () => {
+ let fn = () => true;
+
+ // we want to navigate so that `/about` is the previous entry in the
+ // stack here since it has a loader that won't resolve immediately
+ let initialEntries = ["/", "/about", "/contact"];
+ let initialIndex = 2;
+ beforeEach(() => {
+ router = createRouter({
+ history: createMemoryHistory({
+ initialEntries,
+ initialIndex,
+ }),
+ routes,
+ });
+ router.initialize();
+ });
+
+ it("gets a 'proceeding' blocker after proceeding navigation starts", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ router.getBlocker("KEY", fn).proceed?.();
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location: expect.any(Object),
+ });
+ });
+
+ it("gets an 'unblocked' blocker after proceeding navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ router.getBlocker("KEY", fn).proceed?.();
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("navigates after proceeding navigation completes", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ router.getBlocker("KEY", fn).proceed?.();
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.state.location.pathname).toBe("/about");
+ });
+ });
+
+ describe("resets from blocked state", () => {
+ let fn = () => true;
+ it("gets an 'unblocked' blocker after resetting navigation", async () => {
+ router.getBlocker("KEY", fn);
+ await router.navigate(-1);
+ router.getBlocker("KEY", fn).reset?.();
+ expect(router.getBlocker("KEY", fn)).toEqual({
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+ });
+ });
+
+ it("stays at current location after resetting", async () => {
+ router.getBlocker("KEY", fn);
+ let pathnameBeforeNavigation = router.state.location.pathname;
+ await router.navigate(-1);
+ router.getBlocker("KEY", fn).reset?.();
+
+ // wait for '/about' loader so we catch failure if navigation proceeds
+ await sleep(LOADER_LATENCY_MS);
+ expect(router.state.location.pathname).toBe(pathnameBeforeNavigation);
+ });
+ });
+ });
+});
+
+function sleep(n: number = 500) {
+ return new Promise((r) => setTimeout(r, n));
+}
diff --git a/packages/router/__tests__/router-memory-test.ts b/packages/router/__tests__/router-memory-test.ts
index 2a1635fac4..f4d133c518 100644
--- a/packages/router/__tests__/router-memory-test.ts
+++ b/packages/router/__tests__/router-memory-test.ts
@@ -48,6 +48,7 @@ describe("a memory router", () => {
restoreScrollPosition: null,
revalidation: "idle",
fetchers: new Map(),
+ blockers: new Map(),
});
router.dispose();
});
diff --git a/packages/router/__tests__/router-test.ts b/packages/router/__tests__/router-test.ts
index 6e4a7116ed..9cc383b2ee 100644
--- a/packages/router/__tests__/router-test.ts
+++ b/packages/router/__tests__/router-test.ts
@@ -957,6 +957,7 @@ describe("a router", () => {
restoreScrollPosition: null,
revalidation: "idle",
fetchers: new Map(),
+ blockers: new Map(),
});
});
@@ -1018,6 +1019,7 @@ describe("a router", () => {
restoreScrollPosition: false,
revalidation: "idle",
fetchers: new Map(),
+ blockers: new Map(),
});
});
diff --git a/packages/router/history.ts b/packages/router/history.ts
index e8b6c10f7d..fee3e1191f 100644
--- a/packages/router/history.ts
+++ b/packages/router/history.ts
@@ -81,6 +81,11 @@ export interface Update {
* The new location.
*/
location: Location;
+
+ /**
+ * The delta between this location and the former location in the history stack
+ */
+ delta: number;
}
/**
@@ -181,6 +186,7 @@ export interface History {
type HistoryState = {
usr: any;
key?: string;
+ idx: number;
};
const PopStateEventType = "popstate";
@@ -294,7 +300,7 @@ export function createMemoryHistory(
index += 1;
entries.splice(index, entries.length, nextLocation);
if (v5Compat && listener) {
- listener({ action, location: nextLocation });
+ listener({ action, location: nextLocation, delta: 1 });
}
},
replace(to, state) {
@@ -302,14 +308,16 @@ export function createMemoryHistory(
let nextLocation = createMemoryLocation(to, state);
entries[index] = nextLocation;
if (v5Compat && listener) {
- listener({ action, location: nextLocation });
+ listener({ action, location: nextLocation, delta: 0 });
}
},
go(delta) {
action = Action.Pop;
- index = clampIndex(index + delta);
+ let nextIndex = clampIndex(index + delta);
+ let nextLocation = entries[nextIndex];
+ index = nextIndex;
if (listener) {
- listener({ action, location: getCurrentLocation() });
+ listener({ action, location: nextLocation, delta });
}
},
listen(fn: Listener) {
@@ -497,10 +505,11 @@ function createKey() {
/**
* For browser-based histories, we combine the state and key into an object
*/
-function getHistoryState(location: Location): HistoryState {
+function getHistoryState(location: Location, index: number): HistoryState {
return {
usr: location.state,
key: location.key,
+ idx: index,
};
}
@@ -588,10 +597,43 @@ function getUrlBasedHistory(
let action = Action.Pop;
let listener: Listener | null = null;
+ let index = getIndex()!;
+ // Index should only be null when we initialize. If not, it's because the
+ // user called history.pushState or history.replaceState directly, in which
+ // case we should log a warning as it will result in bugs.
+ if (index == null) {
+ index = 0;
+ globalHistory.replaceState({ ...globalHistory.state, idx: index }, "");
+ }
+
+ function getIndex(): number {
+ let state = globalHistory.state || { idx: null };
+ return state.idx;
+ }
+
function handlePop() {
- action = Action.Pop;
- if (listener) {
- listener({ action, location: history.location });
+ let nextAction = Action.Pop;
+ let nextIndex = getIndex();
+
+ if (nextIndex != null) {
+ let delta = nextIndex - index;
+ action = nextAction;
+ index = nextIndex;
+ if (listener) {
+ listener({ action, location: history.location, delta });
+ }
+ } else {
+ warning(
+ false,
+ // TODO: Write up a doc that explains our blocking strategy in detail
+ // and link to it here so people can understand better what is going on
+ // and how to avoid it.
+ `You are trying to block a POP navigation to a location that was not ` +
+ `created by @remix-run/router. The block will fail silently in ` +
+ `production, but in general you should do all navigation with the ` +
+ `router (instead of using window.history.pushState directly) ` +
+ `to avoid this situation.`
+ );
}
}
@@ -600,7 +642,8 @@ function getUrlBasedHistory(
let location = createLocation(history.location, to, state);
if (validateLocation) validateLocation(location, to);
- let historyState = getHistoryState(location);
+ index = getIndex() + 1;
+ let historyState = getHistoryState(location, index);
let url = history.createHref(location);
// try...catch because iOS limits us to 100 pushState calls :/
@@ -613,7 +656,7 @@ function getUrlBasedHistory(
}
if (v5Compat && listener) {
- listener({ action, location: history.location });
+ listener({ action, location: history.location, delta: 1 });
}
}
@@ -622,12 +665,13 @@ function getUrlBasedHistory(
let location = createLocation(history.location, to, state);
if (validateLocation) validateLocation(location, to);
- let historyState = getHistoryState(location);
+ index = getIndex();
+ let historyState = getHistoryState(location, index);
let url = history.createHref(location);
globalHistory.replaceState(historyState, "", url);
if (v5Compat && listener) {
- listener({ action, location: history.location });
+ listener({ action, location: history.location, delta: 0 });
}
}
diff --git a/packages/router/router.ts b/packages/router/router.ts
index e8ceef4abd..21ae862585 100644
--- a/packages/router/router.ts
+++ b/packages/router/router.ts
@@ -32,6 +32,7 @@ import {
joinPaths,
matchRoutes,
resolveTo,
+ warning,
} from "./utils";
////////////////////////////////////////////////////////////////////////////////
@@ -110,14 +111,14 @@ export interface Router {
* Navigate forward/backward in the history stack
* @param to Delta to move in the history stack
*/
- navigate(to: number): void;
+ navigate(to: number): Promise;
/**
* Navigate to the given path
* @param to Path to navigate to
* @param opts Navigation options (method, submission, etc.)
*/
- navigate(to: To, opts?: RouterNavigateOptions): void;
+ navigate(to: To, opts?: RouterNavigateOptions): Promise;
/**
* @internal
@@ -190,6 +191,25 @@ export interface Router {
*/
dispose(): void;
+ /**
+ * @internal
+ * PRIVATE - DO NOT USE
+ *
+ * Get a navigation blocker
+ * @param key The identifier for the blocker
+ * @param fn The blocker function implementation
+ */
+ getBlocker(key: string, fn: BlockerFunction): Blocker;
+
+ /**
+ * @internal
+ * PRIVATE - DO NOT USE
+ *
+ * Delete a navigation blocker
+ * @param key The identifier for the blocker
+ */
+ deleteBlocker(key: string): void;
+
/**
* @internal
* PRIVATE - DO NOT USE
@@ -275,6 +295,11 @@ export interface RouterState {
* Map of current fetchers
*/
fetchers: Map;
+
+ /**
+ * Map of current blockers
+ */
+ blockers: Map;
}
/**
@@ -460,6 +485,35 @@ type FetcherStates = {
export type Fetcher =
FetcherStates[keyof FetcherStates];
+interface BlockerBlocked {
+ state: "blocked";
+ reset(): void;
+ proceed(): void;
+ location: Location;
+}
+
+interface BlockerUnblocked {
+ state: "unblocked";
+ reset: undefined;
+ proceed: undefined;
+ location: undefined;
+}
+
+interface BlockerProceeding {
+ state: "proceeding";
+ reset: undefined;
+ proceed: undefined;
+ location: Location;
+}
+
+export type Blocker = BlockerUnblocked | BlockerBlocked | BlockerProceeding;
+
+export type BlockerFunction = (args: {
+ currentLocation: Location;
+ nextLocation: Location;
+ historyAction: HistoryAction;
+}) => boolean;
+
interface ShortCircuitable {
/**
* startNavigation does not need to complete the navigation because we
@@ -561,6 +615,13 @@ export const IDLE_FETCHER: FetcherStates["Idle"] = {
formData: undefined,
};
+export const IDLE_BLOCKER: BlockerUnblocked = {
+ state: "unblocked",
+ proceed: undefined,
+ reset: undefined,
+ location: undefined,
+};
+
const isBrowser =
typeof window !== "undefined" &&
typeof window.document !== "undefined" &&
@@ -636,50 +697,76 @@ export function createRouter(init: RouterInit): Router {
actionData: (init.hydrationData && init.hydrationData.actionData) || null,
errors: (init.hydrationData && init.hydrationData.errors) || initialErrors,
fetchers: new Map(),
+ blockers: new Map(),
};
// -- Stateful internal variables to manage navigations --
// Current navigation in progress (to be committed in completeNavigation)
let pendingAction: HistoryAction = HistoryAction.Pop;
+
// Should the current navigation prevent the scroll reset if scroll cannot
// be restored?
let pendingPreventScrollReset = false;
+
// AbortController for the active navigation
let pendingNavigationController: AbortController | null;
+
// We use this to avoid touching history in completeNavigation if a
// revalidation is entirely uninterrupted
let isUninterruptedRevalidation = false;
+
// Use this internal flag to force revalidation of all loaders:
// - submissions (completed or interrupted)
// - useRevalidate()
// - X-Remix-Revalidate (from redirect)
let isRevalidationRequired = false;
+
// Use this internal array to capture routes that require revalidation due
// to a cancelled deferred on action submission
let cancelledDeferredRoutes: string[] = [];
+
// Use this internal array to capture fetcher loads that were cancelled by an
// action navigation and require revalidation
let cancelledFetcherLoads: string[] = [];
+
// AbortControllers for any in-flight fetchers
let fetchControllers = new Map();
+
// Track loads based on the order in which they started
let incrementingLoadId = 0;
+
// Track the outstanding pending navigation data load to be compared against
// the globally incrementing load when a fetcher load lands after a completed
// navigation
let pendingNavigationLoadId = -1;
+
// Fetchers that triggered data reloads as a result of their actions
let fetchReloadIds = new Map();
+
// Fetchers that triggered redirect navigations from their actions
let fetchRedirectIds = new Set();
+
// Most recent href/match for fetcher.load calls for fetchers
let fetchLoadMatches = new Map();
+
// Store DeferredData instances for active route matches. When a
// route loader returns defer() we stick one in here. Then, when a nested
// promise resolves we update loaderData. If a new navigation starts we
// cancel active deferreds for eliminated routes.
let activeDeferreds = new Map();
+ // We ony support a single active blocker at the moment since we don't have
+ // any compelling use cases for multi-blocker yet
+ let activeBlocker: string | null = null;
+
+ // Store blocker functions in a separate Map outside of router state since
+ // we don't need to update UI state if they change
+ let blockerFunctions = new Map();
+
+ // Flag to ignore the next history update, so we can revert the URL change on
+ // a POP navigation that was blocked by the user without touching router state
+ let ignoreNextHistoryUpdate = false;
+
// Initialize the router, all side effects should be kicked off from here.
// Implemented as a Fluent API for ease of:
// let router = createRouter(init).initialize();
@@ -687,8 +774,48 @@ export function createRouter(init: RouterInit): Router {
// If history informs us of a POP navigation, start the navigation but do not update
// state. We'll update our own state once the navigation completes
unlistenHistory = init.history.listen(
- ({ action: historyAction, location }) =>
- startNavigation(historyAction, location)
+ ({ action: historyAction, location, delta }) => {
+ // Ignore this event if it was just us resetting the URL from a
+ // blocked POP navigation
+ if (ignoreNextHistoryUpdate) {
+ ignoreNextHistoryUpdate = false;
+ return;
+ }
+
+ let blockerKey = shouldBlockNavigation({
+ currentLocation: state.location,
+ nextLocation: location,
+ historyAction,
+ });
+ if (blockerKey) {
+ // Restore the URL to match the current UI, but don't update router state
+ ignoreNextHistoryUpdate = true;
+ init.history.go(delta * -1);
+
+ // Put the blocker into a blocked state
+ updateBlocker(blockerKey, {
+ state: "blocked",
+ location,
+ proceed() {
+ updateBlocker(blockerKey!, {
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location,
+ });
+ // Re-do the same POP navigation we just blocked
+ init.history.go(delta);
+ },
+ reset() {
+ deleteBlocker(blockerKey!);
+ updateState({ blockers: new Map(router.state.blockers) });
+ },
+ });
+ return;
+ }
+
+ return startNavigation(historyAction, location);
+ }
);
// Kick off initial data load if needed. Use Pop to avoid modifying history
@@ -707,6 +834,7 @@ export function createRouter(init: RouterInit): Router {
subscribers.clear();
pendingNavigationController && pendingNavigationController.abort();
state.fetchers.forEach((_, key) => deleteFetcher(key));
+ state.blockers.forEach((_, key) => deleteBlocker(key));
}
// Subscribe to state updates for the router
@@ -771,6 +899,12 @@ export function createRouter(init: RouterInit): Router {
)
: state.loaderData;
+ // On a successful navigation we can assume we got through all blockers
+ // so we can start fresh
+ for (let [key] of blockerFunctions) {
+ deleteBlocker(key);
+ }
+
updateState({
...newState, // matches, errors, fetchers go through as-is
actionData,
@@ -785,6 +919,7 @@ export function createRouter(init: RouterInit): Router {
? false
: getSavedScrollPosition(location, newState.matches || state.matches),
preventScrollReset: pendingPreventScrollReset,
+ blockers: new Map(state.blockers),
});
if (isUninterruptedRevalidation) {
@@ -819,16 +954,17 @@ export function createRouter(init: RouterInit): Router {
let { path, submission, error } = normalizeNavigateOptions(to, opts);
- let location = createLocation(state.location, path, opts && opts.state);
+ let currentLocation = state.location;
+ let nextLocation = createLocation(state.location, path, opts && opts.state);
// When using navigate as a PUSH/REPLACE we aren't reading an already-encoded
// URL from window.location, so we need to encode it here so the behavior
// remains the same as POP and non-data-router usages. new URL() does all
// the same encoding we'd get from a history.pushState/window.location read
// without having to touch history
- location = {
- ...location,
- ...init.history.encodeLocation(location),
+ nextLocation = {
+ ...nextLocation,
+ ...init.history.encodeLocation(nextLocation),
};
let userReplace = opts && opts.replace != null ? opts.replace : undefined;
@@ -856,7 +992,35 @@ export function createRouter(init: RouterInit): Router {
? opts.preventScrollReset === true
: undefined;
- return await startNavigation(historyAction, location, {
+ let blockerKey = shouldBlockNavigation({
+ currentLocation,
+ nextLocation,
+ historyAction,
+ });
+ if (blockerKey) {
+ // Put the blocker into a blocked state
+ updateBlocker(blockerKey, {
+ state: "blocked",
+ location: nextLocation,
+ proceed() {
+ updateBlocker(blockerKey!, {
+ state: "proceeding",
+ proceed: undefined,
+ reset: undefined,
+ location: nextLocation,
+ });
+ // Send the same navigation through
+ navigate(to, opts);
+ },
+ reset() {
+ deleteBlocker(blockerKey!);
+ updateState({ blockers: new Map(state.blockers) });
+ },
+ });
+ return;
+ }
+
+ return await startNavigation(historyAction, nextLocation, {
submission,
// Send through the formData serialization error if we have one so we can
// render at the right error boundary after we match routes
@@ -1926,6 +2090,84 @@ export function createRouter(init: RouterInit): Router {
return yeetedKeys.length > 0;
}
+ function getBlocker(key: string, fn: BlockerFunction) {
+ let blocker: Blocker = state.blockers.get(key) || IDLE_BLOCKER;
+
+ if (blockerFunctions.get(key) !== fn) {
+ blockerFunctions.set(key, fn);
+ if (activeBlocker == null) {
+ // This is now the active blocker
+ activeBlocker = key;
+ } else if (key !== activeBlocker) {
+ warning(false, "A router only supports one blocker at a time");
+ }
+ }
+
+ return blocker;
+ }
+
+ function deleteBlocker(key: string) {
+ state.blockers.delete(key);
+ blockerFunctions.delete(key);
+ if (activeBlocker === key) {
+ activeBlocker = null;
+ }
+ }
+
+ // Utility function to update blockers, ensuring valid state transitions
+ function updateBlocker(key: string, newBlocker: Blocker) {
+ let blocker = state.blockers.get(key) || IDLE_BLOCKER;
+
+ // Poor mans state machine :)
+ // https://mermaid.live/edit#pako:eNqVkc9OwzAMxl8l8nnjAYrEtDIOHEBIgwvKJTReGy3_lDpIqO27k6awMG0XcrLlnz87nwdonESogKXXBuE79rq75XZO3-yHds0RJVuv70YrPlUrCEe2HfrORS3rubqZfuhtpg5C9wk5tZ4VKcRUq88q9Z8RS0-48cE1iHJkL0ugbHuFLus9L6spZy8nX9MP2CNdomVaposqu3fGayT8T8-jJQwhepo_UtpgBQaDEUom04dZhAN1aJBDlUKJBxE1ceB2Smj0Mln-IBW5AFU2dwUiktt_2Qaq2dBfaKdEup85UV7Yd-dKjlnkabl2Pvr0DTkTreM
+ invariant(
+ (blocker.state === "unblocked" && newBlocker.state === "blocked") ||
+ (blocker.state === "blocked" && newBlocker.state === "blocked") ||
+ (blocker.state === "blocked" && newBlocker.state === "proceeding") ||
+ (blocker.state === "blocked" && newBlocker.state === "unblocked") ||
+ (blocker.state === "proceeding" && newBlocker.state === "unblocked"),
+ `Invalid blocker state transition: ${blocker.state} -> ${newBlocker.state}`
+ );
+
+ state.blockers.set(key, newBlocker);
+ updateState({ blockers: new Map(state.blockers) });
+ }
+
+ function shouldBlockNavigation({
+ currentLocation,
+ nextLocation,
+ historyAction,
+ }: {
+ currentLocation: Location;
+ nextLocation: Location;
+ historyAction: HistoryAction;
+ }): string | undefined {
+ if (activeBlocker == null) {
+ return;
+ }
+
+ // We only allow a single blocker at the moment. This will need to be
+ // updated if we enhance to support multiple blockers in the future
+ let blockerFunction = blockerFunctions.get(activeBlocker);
+ invariant(
+ blockerFunction,
+ "Could not find a function for the active blocker"
+ );
+ let blocker = state.blockers.get(activeBlocker);
+
+ if (blocker && blocker.state === "proceeding") {
+ // If the blocker is currently proceeding, we don't need to re-check
+ // it and can let this navigation continue
+ return;
+ }
+
+ // At this point, we know we're unblocked/blocked so we need to check the
+ // user-provided blocker function
+ if (blockerFunction({ currentLocation, nextLocation, historyAction })) {
+ return activeBlocker;
+ }
+ }
+
function cancelActiveDeferreds(
predicate?: (routeId: string) => boolean
): string[] {
@@ -2025,6 +2267,8 @@ export function createRouter(init: RouterInit): Router {
getFetcher,
deleteFetcher,
dispose,
+ getBlocker,
+ deleteBlocker,
_internalFetchControllers: fetchControllers,
_internalActiveDeferreds: activeDeferreds,
};
diff --git a/packages/router/utils.ts b/packages/router/utils.ts
index aca20ae7f7..1a01048c3a 100644
--- a/packages/router/utils.ts
+++ b/packages/router/utils.ts
@@ -900,7 +900,7 @@ export function warning(cond: any, message: string): void {
if (typeof console !== "undefined") console.warn(message);
try {
- // Welcome to debugging React Router!
+ // Welcome to debugging @remix-run/router!
//
// This error is thrown as a convenience so you can more easily
// find the source for a warning that appears in the console by
diff --git a/rollup.config.js b/rollup.config.js
index d4f780327f..ba258c604f 100644
--- a/rollup.config.js
+++ b/rollup.config.js
@@ -2,9 +2,15 @@ const fs = require("fs");
const path = require("path");
module.exports = function rollup(options) {
- return fs
- .readdirSync("packages")
+ return [
+ "router",
+ "react-router",
+ "react-router-dom",
+ "react-router-dom-v5-compat",
+ "react-router-native",
+ ]
.flatMap((dir) => {
+ // if (dir !== "router") return null;
let configPath = path.join("packages", dir, "rollup.config.js");
try {
fs.readFileSync(configPath);