Merge pull request #10449 from marmelab/doc/scrollToTop

[Doc] Impove `scrollToTop` in buttons doc and document `_scrollToTop` in `useRedirect`

docs/Buttons.md

@@ -599,6 +599,14 @@ const PostList = () => (
 
 It also supports [all the other `<Button>` props](#button).
 
+### `scrollToTop`
+
+By default, `<CloneButton>` scrolls the page to the top after redirecting to the create view. You can disable it as follows:
+
+```jsx
+const CloneButtonWithoutScrollToTop = () => <CloneButton scrollToTop={false} />
+```
+
 ### Access Control
 
 If you want to control whether this button should be displayed based on users permissions, use the `<CloneButton>` exported by the `@react-admin/ra-rbac` Enterprise package.
@@ -690,6 +698,14 @@ It also supports [all the other `<Button>` props](#button).
 
 **Tip:** To allow users to create a record without leaving the current view, use the [`<CreateInDialogButton>`](./CreateInDialogButton.md) component.
 
+### `scrollToTop`
+
+By default, `<CreateButton>` scrolls the page to the top after redirecting. You can disable it as follows:
+
+```jsx
+const CreateButtonWithoutScrollToTop = () => <CreateButton scrollToTop={false} />
+```
+
 ### `sx`: CSS API
 
 | Rule name                   | Description                                                        |
@@ -963,6 +979,14 @@ It also supports [all the other `<Button>` props](#button).
 
 **Tip:** To allow users to edit a record without leaving the current view, use the [`<EditInDialogButton>`](./EditInDialogButton.md) component.
 
+### `scrollToTop`
+
+By default, `<EditButton>` scrolls the page to the top after redirecting. You can disable it as follows:
+
+```jsx
+const EditButtonWithoutScrollToTop = () => <EditButton scrollToTop={false} />
+```
+
 ### Access Control
 
 If your `authProvider` implements [Access Control](./Permissions.md#access-control), `<EditButton>` will only render if the user has the "edit" access to the related resource.
@@ -1117,14 +1141,23 @@ export const PostShow = () => (
 
 ### Props
 
-| Prop       | Required | Type            | Default          | Description                                  |
-| ---------- | -------- | --------------- | ---------------- | -------------------------------------------- |
-| `resource` | Optional | `string`        | -                | target resource, e.g. 'posts'                |
-| `label`    | Optional | `string`        | 'ra.action.list' | label or translation message to use          |
-| `icon`     | Optional | `ReactElement`  | -                | iconElement, e.g. `<CommentIcon />`          |
+| Prop          | Required | Type            | Default          | Description                                    |
+| ------------- | -------- | --------------- | ---------------- | ---------------------------------------------- |
+| `resource`    | Optional | `string`        | -                | target resource, e.g. 'posts'                  |
+| `label`       | Optional | `string`        | 'ra.action.list' | label or translation message to use            |
+| `icon`        | Optional | `ReactElement`  | -                | iconElement, e.g. `<CommentIcon />`            |
+| `scrollToTop` | Optional | `boolean`       | `true`           | Scroll to top after link                       |
 
 It also supports [all the other `<Button>` props](#button).
 
+### `scrollToTop`
+
+By default, `<ListButton>` scrolls the page to the top after redirecting. You can disable it as follows:
+
+```jsx
+const ListButtonWithoutScrollToTop = () => <ListButton scrollToTop={false} />
+```
+
 ### Access Control
 
 If your `authProvider` implements [Access Control](./Permissions.md#access-control), `<ListButton>` will only render if the user has the "list" access to the related resource.
@@ -1265,6 +1298,14 @@ It also supports [all the other `<Button>` props](#button).
 
 **Tip**: If you want to link to the Show view manually, use the `/{resource}/{record.id}/show` location.
 
+### `scrollToTop`
+
+By default, `<ShowButton>` scrolls the page to the top after redirecting. You can disable it as follows:
+
+```jsx
+const ShowButtonWithoutScrollToTop = () => <ShowButton scrollToTop={false} />
+```
+
 ### Access Control
 
 If your `authProvider` implements [Access Control](./Permissions.md#access-control), `<ShowButton>` will only render if the user has the "show" access to the related resource.

docs/useRedirect.md

@@ -7,6 +7,8 @@ title: "useRedirect"
 
 This hook returns a function that redirects the user to another page.
 
+## Usage
+
 ```jsx
 import { useRedirect } from 'react-admin';
 
@@ -20,13 +22,14 @@ const DashboardButton = () => {
 ```
 
 The callback takes 5 arguments:
- - The page to redirect the user to ('list', 'create', 'edit', 'show', a function or a custom path)
- - The current `resource`
- - The `id` of the record to redirect to (if any)
- - A record-like object to be passed to the first argument, when the first argument is a function
- - A `state` to be set to the location
 
-Here are more examples of `useRedirect` calls: 
+- The page to redirect the user to ('list', 'create', 'edit', 'show', a function or a custom path)
+- The current `resource`
+- The `id` of the record to redirect to (if any)
+- A record-like object to be passed to the first argument, when the first argument is a function
+- A `state` to be set to the location
+
+Here are more examples of `useRedirect` calls:
 
 ```jsx
 // redirect to the post list page
@@ -35,14 +38,8 @@ redirect('list', 'posts');
 redirect('edit', 'posts', 1);
 // redirect to the post creation page:
 redirect('create', 'posts');
-// redirect to the result of a function
-redirect((resource, id, data) => { 
-    return data.hasComments ? '/comments' : '/posts';
-}, 'posts', 1, { hasComments: true });
 // redirect to edit view with state data
 redirect('edit', 'posts', 1, {}, { record: { post_id: record.id } });
-// do not redirect (resets the record form)
-redirect(false);
 ```
 
 Note that `useRedirect` allows redirection to an absolute URL outside the current React app.
@@ -68,4 +65,48 @@ const MyPageButton = () => {
     }
     return <button onClick={handleClick}>My page</button>;
 };
-```
+```
+
+## Redirect function
+
+`useRedirect` allows you to redirect to the result of a function as follows:
+
+```jsx
+redirect((resource, id, data) => { 
+    return data.hasComments ? '/comments' : '/posts';
+}, 'posts', 1, { hasComments: true });
+```
+
+Your function can also return an object containing a `pathname` and optionally some keys of [a `NavigateOptions` object](https://api.reactrouter.com/dev/interfaces/react_router.NavigateOptions.html).
+
+```jsx
+redirect((resource, id, data) => { 
+    return {
+        pathname: `/${resource}/1`,
+        state: { record: { id: 1, foo: 'bar' } },
+        flushSync: true,
+        preventScrollReset: true,
+        replace: false,
+        viewTransition: true,
+    };
+});
+```
+
+## Disable Scroll To Top
+
+By default, react-admin scrolls to top on each redirection. You can disable it by passing a `_scrollToTop: false` option in the 5th argument:
+
+```jsx
+redirect(`/deals/${deal.id}/show`, undefined, undefined, undefined, {
+    _scrollToTop: false,
+});
+```
+
+## Reset the record form
+
+`useRedirect` resets the record form, so you can use the `redirect` function to reset it without redirecting as follows:
+
+```jsx
+// do not redirect (resets the record form)
+redirect(false);
+```