From 2619c56274ebe568530f29bbb4de1c2b30268645 Mon Sep 17 00:00:00 2001
From: erwanMarmelab <erwan@marmelab.com>
Date: Sun, 4 Feb 2024 23:26:36 +0100
Subject: [PATCH 1/3] update doc

---
 docs/Breadcrumb.md                           | 100 +++++++++++++++----
 docs/IconMenu.md                             |  37 ++++++-
 docs/MultiLevelMenu.md                       |  27 +++--
 docs/img/multilevelmenu.png                  | Bin 0 -> 14979 bytes
 docs/useDefineAppLocation.md                 |  72 ++++++++++++-
 examples/simple/src/comments/CommentEdit.tsx |  22 ++++
 6 files changed, 218 insertions(+), 40 deletions(-)
 create mode 100644 docs/img/multilevelmenu.png

diff --git a/docs/Breadcrumb.md b/docs/Breadcrumb.md
index 39170a77707..2147f74b613 100644
--- a/docs/Breadcrumb.md
+++ b/docs/Breadcrumb.md
@@ -5,7 +5,7 @@ title: "The Breadcrumb Component"
 
 # `<Breadcrumb>`
 
-This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component renders a breadcrumb path that automatically adapts to the page location. It helps users navigate large web applications. 
+This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component renders a breadcrumb path that automatically adapts to the page location. It helps users navigate large web applications.
 
 <video controls autoplay playsinline muted loop width="100%">
   <source src="https://marmelab.com/ra-enterprise/modules/assets/ra-navigation/latest/breadcumb-nested-resource.webm" type="video/webm" />
@@ -38,10 +38,12 @@ export const MyLayout = ({ children, ...rest }) => (
 );
 ```
 
-**Tip**: The layout must be wrapped with `<AppLocationContext>`, as `<Breadcrumb>` reads the app location from this context and not the URL. Layout components from `ra-navigation` ([`<ContainerLayout>`](./ContainerLayout.md) or `<SolarLayout>`) already include that context, so it's not necessary to include it in the custom layout. 
-    
+**Tip**: The layout must be wrapped with `<AppLocationContext>`, as `<Breadcrumb>` reads the app location from this context and not the URL. Layout components from `ra-navigation` ([`<ContainerLayout>`](./ContainerLayout.md) or `<SolarLayout>`) already include that context, so it's not necessary to include it in the custom layout.
+
+**Tip:** The `ra-enterprise` package exports an alternative `<Layout>`, which contains a pre-configured `<Breadcrumb>` that renders breadcrumb paths for all resources.
+
 Next, set this custom layout as the [`<Admin layout>`](./Admin.md#layout) component:
-    
+
 ```jsx
 import { Admin } from 'react-admin';
 import { DataProvider } from './dataProvider';
@@ -105,10 +107,10 @@ export const MyLayout = ({ children, ...rest }) => (
 
 With this setup, the breadcrumb on the post pages now renders as:
 
--   "Dashboard / Posts" on the Post List page
--   "Dashboard / Posts / Lorem ipsum" on the Post Edition page with id = 1
--   "Dashboard / Posts / Lorem ipsum" on the Post Show page with id = 1
--   "Dashboard / Posts / Create" on the Post Creation page
+-   "🏠️ / Posts" on the Post List page
+-   "🏠️ / Posts / Lorem ipsum" on the Post Edition page with id = 1
+-   "🏠️ / Posts / Lorem ipsum" on the Post Show page with id = 1
+-   "🏠️ / Posts / Create" on the Post Creation page
 
 You can customize the breadcrumb path of each page, as well as add custom pages to the breadcrumb, by adding `children` to the `<Breadcrumb>` component. See [the `children` section](#children) below for more information.
 
@@ -125,15 +127,23 @@ You don't need to define the app location for CRUD pages as react-admin does it
 -   Edit: `[resource].edit`. The location also contains the current `record`
 -   Show: `[resource].show`. The location also contains the current `record`
 
-However, you can customize these default app locations in your CRUD pages, and you must [define the location for custom pages](#adding-custom-pages). 
+However, you can customize these default app locations in your CRUD pages, and you must [define the location for custom pages](#adding-custom-pages).
+
+To leverage the provided components such as the [`<Breadcrumb>`](#breadcrumb) or [`<MultiLevelMenu>`](./MultiLevelMenu), the layout must be wrapped with `<AppLocationContext>`.
+
+Layout components from `ra-navigation` ([`<ContainerLayout>`](./ContainerLayout) or [`<SolarLayout>`](./SolarLayout)) already include that context, so you can skip that step if you are using one of these layouts.
+
+If, however, you are using the default `<Layout>` component from `react-admin`, or a custom layout, you must wrap it with `<AppLocationContext>`:
 
 ## Props
 
-| Prop        | Required | Type                | Default  | Description                            |
-| ----------- | -------- | ------------------- | -------- | -------------------------------------- |
-| `children`  | Optional | `ReactNode`         | -        | The Breadcrumb Items to be rendered.   |
-| `separator` | Optional | `string | function` | ' / '    | The character user as separator        |
-| `sx`        | Optional | `SxProps`           | -        | Style overrides, powered by MUI System |
+| Prop           | Required | Type               | Default | Description                                                                          |
+| -------------- | -------- | ------------------ | ------- | ------------------------------------------------------------------------------------ |
+| `children`     | Optional | `ReactNode`        | -       | The Breadcrumb Items to be rendered.                                                 |
+| `dashboard`    | Optional | `ReactNode`        | -       | The dashboard component, used to determine if the Admin has a dashboard.             |
+| `hasDashboard` | Optional | boolean            | -       | Alternative to `dashboard`. Set to `true` to add a dashboard item to the breadcrumb. |
+| `separator`    | Optional | string or function | ' / '   | The character user as separator                                                      |
+| `sx`           | Optional | `SxProps`          | -       | Style overrides, powered by MUI System                                               |
 
 Additional props are passed down to the root `<nav>` component.
 
@@ -451,7 +461,51 @@ const MyBreadcrumb = () => (
 );
 ```
 
-Check the [`<Breadcrumb.ResourceItem>`](#breadcrumbresourceitem) section for more information. 
+Check the [`<Breadcrumb.ResourceItem>`](#breadcrumbresourceitem) section for more information.
+
+## `<Breadcrumb.DashboardItem>`
+
+A version of the `<Breadcrumb.Item>` dedicated to the dashboard.
+
+It is convenient for customizing the dashboard item label.
+
+```tsx
+const MyBreadcrumbCustomHome = () => (
+    <Breadcrumb hasDashboard>
+        <Breadcrumb.DashboardItem label="My Home">
+            <Breadcrumb.ResourceItem resource="posts" />
+            <Breadcrumb.ResourceItem resource="comments" />
+        </Breadcrumb.DashboardItem>
+    </Breadcrumb>
+);
+```
+
+Just like with `<Breadcrumb.Item>`, you can also use a React component as label:
+
+```tsx
+import { Breadcrumb } from '@react-admin/ra-navigation';
+import { Box, Stack } from '@mui/material';
+import { visuallyHidden } from '@mui/utils';
+import CabinIcon from '@mui/icons-material/Cabin';
+
+const MyBreadcrumbCustomHome = () => (
+    <Breadcrumb hasDashboard>
+        <Breadcrumb.DashboardItem
+            label={
+                <Stack direction="row" alignItems="center" spacing={1}>
+                    <CabinIcon />
+                    <Box sx={visuallyHidden}>Dashboard</Box>
+                </Stack>
+            }
+        >
+            <Breadcrumb.ResourceItem resource="posts" />
+            <Breadcrumb.ResourceItem resource="comments" />
+        </Breadcrumb.DashboardItem>
+    </Breadcrumb>
+);
+```
+
+**Tip:** It's a good practice to include a visually hidden placeholder ('Dashboard' in this example) for screen readers when using an icon as label.
 
 ## Using A Dashboard As The Root
 
@@ -474,12 +528,14 @@ export const MyLayout = ({ children, ...rest }) => (
 
 By doing this, the breadcrumb will now show respectively:
 
--   "Dashboard / Posts" on the Post List page
--   "Dashboard / Posts / Show #1" on the Post Show page with id = 1
--   "Dashboard / Posts / Edit #1" on the Post Edition page with id = 1
--   "Dashboard / Posts / Create" on the Post Creation page
+-   "🏠️ / Posts" on the Post List page
+-   "🏠️ / Posts / Show #1" on the Post Show page with id = 1
+-   "🏠️ / Posts / Edit #1" on the Post Edition page with id = 1
+-   "🏠️ / Posts / Create" on the Post Creation page
+
+**Tip:** Even though it is rendered as a 'home' icon (🏠️), the dashboard breadcrumb item also contains the hidden placeholder text 'Dashboard', for screen readers. If you want to customize this text, e.g. to rename "Dashboard" to "Home", provide a [custom translation](https://marmelab.com/react-admin/Translation.html) for the `ra.page.dashboard` message.
 
-If you want to customize the dashboard breadcrumb item label, e.g. to rename "Dashboard" to "Home", provide a [custom translation](./Translation.md) for the `ra.page.dashboard` message. 
+If you want to customize the dashboard breadcrumb item label, e.g. to rename "Dashboard" to "Home", provide a [custom translation](./Translation.md) for the `ra.page.dashboard` message.
 
 ## Adding Custom Pages
 
@@ -604,7 +660,7 @@ const App = () => (
 
 ## Nested Resources
 
-When using [nested resources](./Resource.md#nested-resources), you should create breadcrumb items for the sub-resources. 
+When using [nested resources](./Resource.md#nested-resources), you should create breadcrumb items for the sub-resources.
 
 For instance, the screencast at the top of this page shows a `songs` resource nested in an `artists` resource, using the following routes:
 
@@ -838,4 +894,4 @@ const MyBreadcrumb = () => (
 );
 ```
 
-As you see, you can compose Breadcrumb item elements at will. 
\ No newline at end of file
+As you see, you can compose Breadcrumb item elements at will.
diff --git a/docs/IconMenu.md b/docs/IconMenu.md
index b93f7b3a71d..21f906f508b 100644
--- a/docs/IconMenu.md
+++ b/docs/IconMenu.md
@@ -13,10 +13,13 @@ This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" s
   Your browser does not support the video tag.
 </video>
 
+Sometimes, even menus with sub-menus are not enough to organize the navigation. `ra-navigation` offers an alternative UI for that case: a vertical bar with small items, where the menu label renders underneath the icon. Clicking on any of those items opens a panel containing as many navigation links as you like, laid out as you wish.
+
 Test it live on [the Enterprise Edition Storybook](https://storybook.ra-enterprise.marmelab.com/?path=/story/ra-navigation-iconmenu--basic).
 
 ## Usage
 
+
 Create a custom menu component using the `<IconMenu>` and `<IconMenu.Item>` components from the `ra-navigation` package:
 
 ```jsx
@@ -28,15 +31,16 @@ import MusicIcon from '@mui/icons-material/MusicNote';
 import PeopleIcon from '@mui/icons-material/People';
 
 const MyMenu = () => (
-  <IconMenu>
+  <IconMenu variant="categories">
     <IconMenu.Item name="dashboard" to="/" label="Dashboard" icon={<DashboardIcon />} />
     <IconMenu.Item name="songs" to="/songs" label="Songs" icon={<MusicIcon />}  />
+    {/* The empty filter is required to avoid falling back to the previously set filter */}
     <IconMenu.Item name="artists" to="/artists" label="Artists" icon={<PeopleIcon />} />
   </IconMenu>
 );
 ```
 
-Then, create a custom layout using [the `<Layout>` component](./Layout.md) and pass your custom menu component to it. Make sure you wrap the layout with the `<AppLocationContext>` component. 
+Then, create a custom layout using [the `<Layout>` component](./Layout.md) and pass your custom menu component to it. Make sure you wrap the layout with the `<AppLocationContext>` component.
 
 ```jsx
 // in src/MyLayout.js
@@ -52,7 +56,7 @@ export const MyLayout = (props) => (
 );
 ```
 
-`<AppLocationContext>` is necessary because `ra-navigation` doesn't use the URL to detect the current location. Instead, page components *declare* their location using a custom hook (`useDefineAppLocation()`). This allows complex site maps, with multiple levels of nesting. Check [the ra-navigation documentation](https://marmelab.com/ra-enterprise/modules/ra-navigation) to learn more about App Location. 
+`<AppLocationContext>` is necessary because `ra-navigation` doesn't use the URL to detect the current location. Instead, page components *declare* their location using a custom hook (`useDefineAppLocation()`). This allows complex site maps, with multiple levels of nesting. Check [the ra-navigation documentation](https://marmelab.com/ra-enterprise/modules/ra-navigation) to learn more about App Location.
 
 Finally, pass this custom layout to the `<Admin>` component. You should apply the theme provided by ra-navigation:
 
@@ -74,6 +78,29 @@ const App = () => (
 );
 ```
 
+In order to adjust the size of the React-Admin `<Sidebar>` component according to the categories, you should either apply the `theme` provided by the `@react-admin/ra-navigation` package (as above), or merge it in your own custom theme.
+
+```tsx
+import merge from 'lodash/merge';
+import { defaultTheme } from 'react-admin';
+import { ThemeOptions } from '@react-admin/ra-navigation';
+export const theme: ThemeOptions = merge({}, defaultTheme, {
+    sidebar: {
+        width: 96,
+        closedWidth: 48,
+    },
+    overrides: {
+        RaSidebar: {
+            fixed: {
+                zIndex: 1200,
+            },
+        },
+    },
+});
+```
+
+**Tip**: With `<IconMenu />`, labels may disappear when the sidebar is in reduced mode. This is because of the internal workings of react-admin. That's why we recommend implementing your own `<AppBar />`, and hiding the Hamburger Button. `<IconMenu />` is thin enough not to interfere with the navigation anyway.
+
 ## Props
 
 | Prop        | Required | Type        | Default  | Description                            |
@@ -127,7 +154,7 @@ To override the style of `<IconMenu>` using the [application-wide style override
 The `<IconMenu.Item>` component displays a menu item with a label and an icon.
 
 ```jsx
-<IconMenu.Item 
+<IconMenu.Item
     name="dashboard"
     to="/"
     label="Dashboard"
@@ -212,7 +239,7 @@ import LabelIcon from '@mui/icons-material/Label';
 
 export const MyMenu = () => {
     const resources = useResourceDefinitions();
-    
+
     return (
         <IconMenu>
             {Object.keys(resources).map(name => (
diff --git a/docs/MultiLevelMenu.md b/docs/MultiLevelMenu.md
index 5014e3c72ee..488cf689dbb 100644
--- a/docs/MultiLevelMenu.md
+++ b/docs/MultiLevelMenu.md
@@ -5,7 +5,11 @@ title: "The MultiLevelMenu Component"
 
 # `<MultiLevelMenu>`
 
-This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component adds support for nested sub menus in the left navigation bar. 
+This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component adds support for nested sub menus in the left navigation bar.
+
+![MultiLevelMenu](./img/multilevelmenu.png)
+
+When a React-admin application grows significantly, the default menu might not be the best solution. The `<MultiLevelMenu>` can help unclutter the navigation: it renders a menu with an infinite number of levels and sub-menus. Menu Items that are not at the top level are rendered inside a collapsible panel.
 
 <video controls autoplay playsinline muted loop>
   <source src="https://marmelab.com/ra-enterprise/modules/assets/ra-multilevelmenu-item.webm" type="video/webm" />
@@ -50,7 +54,7 @@ const MyMenu = () => (
 
 Note that each `<MultiLevelMenu.Item>` requires a unique `name` attribute.
 
-Then, create a custom layout using [the `<Layout>` component](./Layout.md) and pass your custom menu component to it. Make sure you wrap the layout with the `<AppLocationContext>` component. 
+Then, create a custom layout using [the `<Layout>` component](./Layout.md) and pass your custom menu component to it. Make sure you wrap the layout with the `<AppLocationContext>` component.
 
 ```jsx
 // in src/MyLayout.js
@@ -66,7 +70,7 @@ export const MyLayout = (props) => (
 );
 ```
 
-`<AppLocationContext>` is necessary because `ra-navigation` doesn't use the URL to detect the current location. Instead, page components *declare* their location using a custom hook (`useDefineAppLocation()`). This allows complex site maps, with multiple levels of nesting. That's the reason why each `<MultiLevelMenu.Item>` requires a unique `name`, that matches a particular page location. 
+`<AppLocationContext>` is necessary because `ra-navigation` doesn't use the URL to detect the current location. Instead, page components *declare* their location using a custom hook (`useDefineAppLocation()`). This allows complex site maps, with multiple levels of nesting. That's the reason why each `<MultiLevelMenu.Item>` requires a unique `name`, that matches a particular page location.
 
 You can set the `AppLocation` for a given page like so:
 
@@ -89,7 +93,7 @@ And then use this `AppLocation` as `name` for `<MultiLevelMenu.Item>`:
 >
 ```
 
-Check [the ra-navigation documentation](https://marmelab.com/ra-enterprise/modules/ra-navigation) to learn more about App Location. 
+Check [the ra-navigation documentation](https://marmelab.com/ra-enterprise/modules/ra-navigation) to learn more about App Location.
 
 Finally, pass this custom layout to the `<Admin>` component
 
@@ -111,11 +115,12 @@ const App = () => (
 
 ## Props
 
-| Prop          | Required | Type        | Default  | Description                            |
-| ------------- | -------- | ----------- | -------- | -------------------------------------- |
-| `children`    | Optional | `ReactNode` | -        | The Menu Items  to be rendered.        |
-| `initialOpen` | Optional | `boolean`   | `false`  | Whether the menu is initially open.    |
-| `sx`          | Optional | `SxProps`   | -        | Style overrides, powered by MUI System |
+| Prop           | Required | Type        | Default  | Description                                                   |
+| -------------- | -------- | ----------- | -------- | ------------------------------------------------------------- |
+| `children`     | Optional | `ReactNode` | -        | The Menu Items  to be rendered.                               |
+| `initialOpen`  | Optional | `boolean`   | `false`  | Whether the menu is initially open.                           |
+| `openItemList` | Optional | `Array`     | -        | List of names of menu items that should be opened by default. |
+| `sx`           | Optional | `SxProps`   | -        | Style overrides, powered by MUI System                        |
 
 Additional props are passed down to the root `<div>` component.
 
@@ -175,7 +180,7 @@ To override the style of `<MultiLevelMenu>` using the [application-wide style ov
 The `<MultiLevelMenu.Item>` component displays a menu item with a label and an icon.
 
 ```jsx
-<MultiLevelMenu.Item 
+<MultiLevelMenu.Item
     name="dashboard"
     to="/"
     label="Dashboard"
@@ -210,7 +215,7 @@ import LabelIcon from '@mui/icons-material/Label';
 
 export const MyMenu = () => {
     const resources = useResourceDefinitions();
-    
+
     return (
         <MultiLevelMenu>
             {Object.keys(resources).map(name => (
diff --git a/docs/img/multilevelmenu.png b/docs/img/multilevelmenu.png
new file mode 100644
index 0000000000000000000000000000000000000000..3ea789f181713dc8766ac2f84f9adfbe25bf152a
GIT binary patch
literal 14979
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
XET^aq_==}W37LzE7cwQT|Mforq1M)v

literal 0
HcmV?d00001

diff --git a/docs/useDefineAppLocation.md b/docs/useDefineAppLocation.md
index c6977c3daf7..a1b55e6eb3b 100644
--- a/docs/useDefineAppLocation.md
+++ b/docs/useDefineAppLocation.md
@@ -5,7 +5,7 @@ title: "useDefineAppLocation"
 
 # `useDefineAppLocation`
 
-This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> hook lets you define the app location for a page, used by components like [`<Breadcrumb>`](./Breadcrumb.md) and [`<IconMenu>`](./IconMenu.md) to render the current location. 
+This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> hook lets you define the app location for a page, used by components like [`<Breadcrumb>`](./Breadcrumb.md) and [`<IconMenu>`](./IconMenu.md) to render the current location.
 
 <video controls autoplay playsinline muted loop width="100%">
   <source src="https://marmelab.com/ra-enterprise/modules/assets/ra-navigation/latest/breadcumb-nested-resource.webm" type="video/webm" />
@@ -13,6 +13,74 @@ This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" s
   Your browser does not support the video tag.
 </video>
 
+In the following example, the `<SongEditForArtist>` component is a [nested resource](https://marmelab.com/react-admin/Resource.html#nested-resources) rendering at the `/artists/:id/songs/:songId` path. It uses `useDefineAppLocation` to define the app location as `artists.edit.songs.edit`, and passes the `record` and `song` objects as parameters to let the breadcrumb component render the record and song names.
+
+```tsx
+import { useParams } from 'react-router-dom';
+import { Edit, SimpleForm, TextInput, DateInput, useGetOne } from 'react-admin';
+import { useDefineAppLocation } from '@react-admin/ra-navigation';
+const SongEditForArtist = () => {
+    const { id, songId } = useParams<{ id: string; songId: string }>();
+    const { data: record } = useGetOne('artists', { id });
+    const { data: song } = useGetOne('songs', { id: songId });
+    useDefineAppLocation('artists.edit.songs.edit', { record, song });
+    return (
+        <Edit resource="songs" id={songId} redirect={`/artists/${id}/songs`}>
+            <SimpleForm>
+                <TextInput source="title" />
+                <DateInput source="released" />
+                <TextInput source="writer" />
+                <TextInput source="producer" />
+                <TextInput source="recordCompany" label="Label" />
+            </SimpleForm>
+        </Edit>
+    );
+};
+```
+
+**Tip**: The `<Edit>` component will call `dataProvider.getOne("songs", { id: songId })` to fetch the song record. Since the `<SongEditForArtist>` component makes the same request, React-admin will deduplicate the calls and only make one request to the dataProvider.
+
+**Tip**: If you don't call `useDefineAppLocation` anywhere on a page, the AppLocationContext will deduce a resource app location from the current URL path (e.g. `artists.edit` for the `/artists/:id` path).
+
+Here is how a custom Breadcrumb would use location `values` to render the record and song names:
+
+```tsx
+const MyBreadcrumb = () => (
+    <Breadcrumb>
+        <Breadcrumb.Item name="artists" label="Artists" to="/artists">
+            <Breadcrumb.Item
+                name="edit"
+                label={({ record }: { record?: Artist }) => record?.name}
+                to={({ record }: { record?: Artist }) =>
+                    `/artists/${record?.id}`
+                }
+            >
+                <Breadcrumb.Item
+                    name="songs"
+                    label="Songs"
+                    to={({ record }: { record?: Artist }) =>
+                        `/artists/${record?.id}/songs`
+                    }
+                >
+                    <Breadcrumb.Item
+                        name="edit"
+                        label={({ song }: { song?: Song }) => song?.title}
+                        to={({ song }: { song?: Song }) =>
+                            `/artists/${song?.artist_id}/songs/${song?.id}`
+                        }
+                    />
+                </Breadcrumb.Item>
+            </Breadcrumb.Item>
+            <Breadcrumb.Item
+                name="create"
+                label="Create"
+                to="/artists/create"
+            />
+        </Breadcrumb.Item>
+    </Breadcrumb>
+);
+```
+
 ## Usage
 
 This component requires that the application layout is wrapped with [`<AppLocationContext>`](./Breadcrumb.md#app-location) (which is already the case for [`<ContainerLayout>`](./ContainerLayout.md) and `<SolarLayout>`):
@@ -66,7 +134,7 @@ const App = () => (
 );
 ```
 
-Components inside the app, like [`<Breadcrumb>`](./Breadcrumb.md), can read the current app location and define custom items for the `'user.preferences'` location. 
+Components inside the app, like [`<Breadcrumb>`](./Breadcrumb.md), can read the current app location and define custom items for the `'user.preferences'` location.
 
 ```jsx
 // in src/MyBreadcrumb.jsx
diff --git a/examples/simple/src/comments/CommentEdit.tsx b/examples/simple/src/comments/CommentEdit.tsx
index 92a094ae064..6a24a1147af 100644
--- a/examples/simple/src/comments/CommentEdit.tsx
+++ b/examples/simple/src/comments/CommentEdit.tsx
@@ -28,6 +28,28 @@ import {
     useCreatePath,
     useRecordContext,
 } from 'react-admin';
+import { Link, useGetRecordRepresentation } from 'react-admin';
+import { Breadcrumbs } from '@mui/material';
+
+export const PostBreadcrumbs = () => {
+    const record = useRecordContext();
+    const getRecordRepresentation = useGetRecordRepresentation('posts');
+    return (
+        <div role="presentation">
+            <Breadcrumbs aria-label="breadcrumb">
+                <Link underline="hover" color="inherit" to="/">
+                    Home
+                </Link>
+                <Link underline="hover" color="inherit" to="/posts">
+                    Posts
+                </Link>
+                <Typography color="text.primary">
+                    {getRecordRepresentation(record)}
+                </Typography>
+            </Breadcrumbs>
+        </div>
+    );
+};
 
 const LinkToRelatedPost = () => {
     const record = useRecordContext();

From a72fcb01bcb341c7ddaffa1d51b5f4c3f119bf19 Mon Sep 17 00:00:00 2001
From: erwanMarmelab <erwan@marmelab.com>
Date: Sun, 4 Feb 2024 23:30:12 +0100
Subject: [PATCH 2/3] fix unnecessary push

---
 examples/simple/src/comments/CommentEdit.tsx | 22 --------------------
 1 file changed, 22 deletions(-)

diff --git a/examples/simple/src/comments/CommentEdit.tsx b/examples/simple/src/comments/CommentEdit.tsx
index 6a24a1147af..92a094ae064 100644
--- a/examples/simple/src/comments/CommentEdit.tsx
+++ b/examples/simple/src/comments/CommentEdit.tsx
@@ -28,28 +28,6 @@ import {
     useCreatePath,
     useRecordContext,
 } from 'react-admin';
-import { Link, useGetRecordRepresentation } from 'react-admin';
-import { Breadcrumbs } from '@mui/material';
-
-export const PostBreadcrumbs = () => {
-    const record = useRecordContext();
-    const getRecordRepresentation = useGetRecordRepresentation('posts');
-    return (
-        <div role="presentation">
-            <Breadcrumbs aria-label="breadcrumb">
-                <Link underline="hover" color="inherit" to="/">
-                    Home
-                </Link>
-                <Link underline="hover" color="inherit" to="/posts">
-                    Posts
-                </Link>
-                <Typography color="text.primary">
-                    {getRecordRepresentation(record)}
-                </Typography>
-            </Breadcrumbs>
-        </div>
-    );
-};
 
 const LinkToRelatedPost = () => {
     const record = useRecordContext();

From a5545f4c49384677debede828f362cef26150d0f Mon Sep 17 00:00:00 2001
From: Gildas Garcia <1122076+djhi@users.noreply.github.com>
Date: Mon, 5 Feb 2024 09:08:19 +0100
Subject: [PATCH 3/3] Format examples

---
 docs/IconMenu.md             | 1 +
 docs/useDefineAppLocation.md | 1 +
 2 files changed, 2 insertions(+)

diff --git a/docs/IconMenu.md b/docs/IconMenu.md
index 21f906f508b..ce3bb867e1b 100644
--- a/docs/IconMenu.md
+++ b/docs/IconMenu.md
@@ -84,6 +84,7 @@ In order to adjust the size of the React-Admin `<Sidebar>` component according t
 import merge from 'lodash/merge';
 import { defaultTheme } from 'react-admin';
 import { ThemeOptions } from '@react-admin/ra-navigation';
+
 export const theme: ThemeOptions = merge({}, defaultTheme, {
     sidebar: {
         width: 96,
diff --git a/docs/useDefineAppLocation.md b/docs/useDefineAppLocation.md
index a1b55e6eb3b..d36cf2d1a29 100644
--- a/docs/useDefineAppLocation.md
+++ b/docs/useDefineAppLocation.md
@@ -19,6 +19,7 @@ In the following example, the `<SongEditForArtist>` component is a [nested resou
 import { useParams } from 'react-router-dom';
 import { Edit, SimpleForm, TextInput, DateInput, useGetOne } from 'react-admin';
 import { useDefineAppLocation } from '@react-admin/ra-navigation';
+
 const SongEditForArtist = () => {
     const { id, songId } = useParams<{ id: string; songId: string }>();
     const { data: record } = useGetOne('artists', { id });