[Doc] Explain how to change page with useNavigation

docs/useRedirect.md

@@ -41,6 +41,8 @@ redirect((resource, id, data) => {
 }, 'posts', 1, { hasComments: true });
 // redirect to edit view with state data
 redirect('edit', 'posts', 1, {}, { record: { post_id: record.id } });
+// redirect to a history Location object
+redirect({ pathname: '/some/path', search: '?query=string', hash: '#hash', state: null, key: 'my_key' });
 // do not redirect (resets the record form)
 redirect(false);
 ```

packages/ra-core/package.json

@@ -30,6 +30,7 @@
         "@hookform/resolvers": "^3.2.0",
         "@testing-library/react": "^14.1.2",
         "@testing-library/react-hooks": "^8.0.1",
+        "@types/history": "^5.0.0",
         "@types/jest": "^29.5.2",
         "@types/jscodeshift": "^0.11.11",
         "@types/node": "^20.10.7",
@@ -52,6 +53,7 @@
         "zod": "^3.22.1"
     },
     "peerDependencies": {
+        "@types/history": "^5.0.0",
         "react": "^18.0.0",
         "react-dom": "^18.0.0",
         "react-hook-form": "^7.43.9",

packages/ra-core/src/routing/useRedirect.stories.tsx

@@ -0,0 +1,107 @@
+import * as React from 'react';
+import { Link, Routes, Route, useLocation } from 'react-router-dom';
+
+import { FakeBrowserDecorator } from '../storybook//FakeBrowser';
+import { useRedirect as useRedirectRA } from './useRedirect';
+
+export default {
+    title: 'ra-core/routing',
+    decorators: [FakeBrowserDecorator],
+};
+
+const Home = () => {
+    const redirect = useRedirectRA();
+    return (
+        <>
+            <h1>Home</h1>
+            <ul>
+                <li>
+                    <button onClick={() => redirect('/dashboard')}>
+                        Dashboard
+                    </button>
+                </li>
+                <li>
+                    <button onClick={() => redirect('list', 'posts')}>
+                        Post list
+                    </button>
+                </li>
+                <li>
+                    <button onClick={() => redirect('edit', 'posts', 123)}>
+                        123th post detail
+                    </button>
+                </li>
+                <li>
+                    <button
+                        onClick={() =>
+                            redirect({
+                                pathname: '/some/path',
+                                search: '?query=string',
+                                hash: '#hash',
+                                state: null,
+                                key: 'my_key',
+                            })
+                        }
+                    >
+                        My page
+                    </button>
+                </li>
+                <li>
+                    <button
+                        onClick={() =>
+                            redirect((resource, id, data) => {
+                                return data?.hasComments ? 'comments' : 'posts';
+                            })
+                        }
+                    >
+                        Redirect function
+                    </button>
+                </li>
+            </ul>
+        </>
+    );
+};
+
+const Dashboard = () => (
+    <div>
+        <h1>Admin dashboard</h1>
+        <Link to="/">Home</Link>
+    </div>
+);
+
+const PostList = () => (
+    <div>
+        <h1>Posts</h1>
+        <Link to="/">Home</Link>
+    </div>
+);
+
+const PostDetail = () => (
+    <div>
+        <h1>Post 123</h1>
+        <Link to="/">Home</Link>
+    </div>
+);
+
+const SomePage = () => {
+    const location = useLocation();
+    return (
+        <div>
+            <h1>My Page</h1>
+            <Link to="/">Home</Link>
+            <hr />
+            <p>Location: {location.pathname}</p>
+            <p>Location: {location.search}</p>
+            <p>Hash: {location.hash}</p>
+        </div>
+    );
+};
+
+export const useRedirect = () => (
+    <Routes>
+        <Route path="/" element={<Home />} />
+        <Route path="/dashboard" element={<Dashboard />} />
+        <Route path="/posts" element={<PostList />} />
+        <Route path="/posts/123" element={<PostDetail />} />
+        <Route path="/some/path" element={<SomePage />} />
+    </Routes>
+);

packages/ra-core/src/routing/useRedirect.ts

@@ -1,5 +1,6 @@
 import { useCallback } from 'react';
 import { useNavigate, To } from 'react-router-dom';
+import { Location } from 'history';
 import { Identifier, RaRecord } from '../types';
 
 import { useBasename } from './useBasename';
@@ -12,7 +13,11 @@ type RedirectToFunction = (
     state?: object
 ) => To;
 
-export type RedirectionSideEffect = CreatePathType | false | RedirectToFunction;
+export type RedirectionSideEffect =
+    | CreatePathType
+    | false
+    | RedirectToFunction
+    | Location;
 
 /**
  * Hook for Redirection Side Effect
@@ -30,6 +35,8 @@ export type RedirectionSideEffect = CreatePathType | false | RedirectToFunction;
  * redirect(false);
  * // redirect to the result of a function
  * redirect((resource, id, data) => ...)
+ * // redirect to a Location object
+ * redirect({ pathname: '/some/path', search: '?query=string', hash: '#hash', state: null, key: 'my_key' });
  */
 export const useRedirect = () => {
     const navigate = useNavigate();
@@ -59,6 +66,9 @@ export const useRedirect = () => {
                     state: { _scrollToTop: true, ...state },
                 });
                 return;
+            } else if (typeof redirectTo === 'object') {
+                navigate(redirectTo);
+                return;
             } else if (
                 typeof redirectTo === 'string' &&
                 redirectTo.startsWith('http') &&
@@ -70,14 +80,21 @@ export const useRedirect = () => {
                 return;
             } else {
                 // redirection to an internal link
-                navigate(createPath({ resource, id, type: redirectTo }), {
-                    state:
-                        // We force the scrollToTop except when navigating to a list
-                        // where this is already done by <RestoreScrollPosition> in <Resource>
-                        redirectTo === 'list'
-                            ? state
-                            : { _scrollToTop: true, ...state },
-                });
+                navigate(
+                    createPath({
+                        resource,
+                        id,
+                        type: redirectTo as CreatePathType,
+                    }),
+                    {
+                        state:
+                            // We force the scrollToTop except when navigating to a list
+                            // where this is already done by <RestoreScrollPosition> in <Resource>
+                            redirectTo === 'list'
+                                ? state
+                                : { _scrollToTop: true, ...state },
+                    }
+                );
                 return;
             }
         },

yarn.lock

@@ -6547,6 +6547,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/history@npm:^5.0.0":
+  version: 5.0.0
+  resolution: "@types/history@npm:5.0.0"
+  dependencies:
+    history: "npm:*"
+  checksum: bce6d8da5217349dec97dfc4d9b65be03166351b86cb3e8764ed92b8b98eced1fc7ecb5bb17f1d7da894d065ffa3a12a8106444c174450a6d596241deef3f0a5
+  languageName: node
+  linkType: hard
+
 "@types/hoist-non-react-statics@npm:^3.3.1":
   version: 3.3.1
   resolution: "@types/hoist-non-react-statics@npm:3.3.1"
@@ -13360,6 +13369,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"history@npm:*":
+  version: 5.3.0
+  resolution: "history@npm:5.3.0"
+  dependencies:
+    "@babel/runtime": "npm:^7.7.6"
+  checksum: 812ec839386222d6437bd78d9f05db32e47d105ada0ad8834b32626919dd2fee7a10001bc489510f93a8069d02f118214bd8d42a82f7cf9daf8e84fbcbbb2016
+  languageName: node
+  linkType: hard
+
 "hoist-non-react-statics@npm:^3.3.0, hoist-non-react-statics@npm:^3.3.1, hoist-non-react-statics@npm:^3.3.2":
   version: 3.3.2
   resolution: "hoist-non-react-statics@npm:3.3.2"
@@ -18686,6 +18704,7 @@ __metadata:
     "@tanstack/react-query": "npm:^5.8.4"
     "@testing-library/react": "npm:^14.1.2"
     "@testing-library/react-hooks": "npm:^8.0.1"
+    "@types/history": "npm:^5.0.0"
     "@types/jest": "npm:^29.5.2"
     "@types/jscodeshift": "npm:^0.11.11"
     "@types/node": "npm:^20.10.7"
@@ -18717,6 +18736,7 @@ __metadata:
     yup: "npm:^0.32.11"
     zod: "npm:^3.22.1"
   peerDependencies:
+    "@types/history": ^5.0.0
     react: ^18.0.0
     react-dom: ^18.0.0
     react-hook-form: ^7.43.9