marmelab · slax57 · Jul 24, 2023 · Jul 24, 2023 · Jul 24, 2023
diff --git a/docs/Datagrid.md b/docs/Datagrid.md
diff --git a/docs/Fields.md b/docs/Fields.md
@@ -368,17 +368,15 @@ const BookEdit = () => (
 );
 ```
 
-## Hiding A Field Label
+## Hiding The Field Label
 
-You can opt out of the label decoration by passing `false` to the `label` prop.
+React-admin Field layout components like [`<Datagrid>`](./Datagrid.md) and [`<SimpleShowLayout>`](./SimpleShowLayout.md) inspect their children and use their `source` prop to set the table headers or the field labels. To opt out of this behavior, pass `false` to the `label` prop.
 
 ```jsx
-// No label will be added
+// No label will be added in SimpleShowLayout
 <TextField source="author.name" label={false} />
 ```
 
-**Note**: This prop has no effect when rendering a field outside a `<Datagrid>`, a `<SimpleShowLayout>`, a `<TabbedShowLayout>`, a `<SimpleForm>`, or a `<TabbedForm>`.
-
 ## Conditional Formatting
 
 If you want to format a field depending on the value, create another component wrapping this field, and set the `sx` prop depending on the field value:

diff --git a/docs/FilterList.md b/docs/FilterList.md
@@ -50,7 +50,7 @@ export const PostFilterSidebar = () => (
 ```
 {% endraw %}
 
-Add this component to the list view using [the `<List aside>` prop](./List.md#aside-side-component):
+Add this component to the list view using [the `<List aside>` prop](./):
 
 ```jsx
 import { PostFilterSidebar } from './PostFilterSidebar';

diff --git a/docs/List.md b/docs/List.md
@@ -52,26 +52,26 @@ You can find more advanced examples of `<List>` usage in the [demos](./Demos.md)
 
 | Prop                      | Required | Type           | Default        | Description                                                                                  |
 |---------------------------|----------|----------------|----------------|----------------------------------------------------------------------------------------------|
-| `children`                | Required | `ReactNode`    | -              | The component to use to render the list of records.                                          |
+| `children`                | Required | `ReactNode`    | -              | The components rendering the list of records.                                          |
 | `actions`                 | Optional | `ReactElement` | -              | The actions to display in the toolbar.                                                       |
 | `aside`                   | Optional | `ReactElement` | -              | The component to display on the side of the list.                                            |
 | `component`               | Optional | `Component`    | `Card`         | The component to render as the root element.                                                 |
 | `debounce`                | Optional | `number`       | `500`          | The debounce delay in milliseconds to apply when users change the sort or filter parameters. |
 | `disable Authentication`  | Optional | `boolean`      | `false`        | Set to `true` to disable the authentication check.                                           |
 | `disable SyncWithLocation`| Optional | `boolean`      | `false`        | Set to `true` to disable the synchronization of the list parameters with the URL.            |
 | `empty`                   | Optional | `ReactElement` | -              | The component to display when the list is empty.                                             |
-| `emptyWhileLoading`       | Optional | `boolean`      | `false`        | Set to `true` to return `null` while the list is loading.                                    |
+| `empty WhileLoading`      | Optional | `boolean`      | `false`        | Set to `true` to return `null` while the list is loading.                                    |
 | `exporter`                | Optional | `function`     | -              | The function to call to export the list.                                                     |
 | `filters`                 | Optional | `ReactElement` | -              | The filters to display in the toolbar.                                                       |
 | `filter`                  | Optional | `object`       | -              | The permanent filter values.                                                                 |
-| `filterDefaultValues`     | Optional | `object`       | -              | The default filter values.                                                                   |
+| `filter DefaultValues`    | Optional | `object`       | -              | The default filter values.                                                                   |
 | `hasCreate`               | Optional | `boolean`      | `false`        | Set to `true` to show the create button.                                                     |
 | `pagination`              | Optional | `ReactElement` | `<Pagination>` | The pagination component to use.                                                             |
 | `perPage`                 | Optional | `number`       | `10`           | The number of records to fetch per page.                                                     |
 | `queryOptions`            | Optional | `object`       | -              | The options to pass to the `useQuery` hook.                                                  |
 | `resource`                | Optional | `string`       | -              | The resource name, e.g. `posts`.                                                             |
 | `sort`                    | Optional | `object`       | -              | The initial sort parameters.                                                                 |
-| `storeKey`                | Optional | `string` | `false` | -              | The key to use to store the current filter & sort. Pass `false` to disable                                         |
+| `storeKey`                | Optional | `string | false` | -            | The key to use to store the current filter & sort. Pass `false` to disable                                         |
 | `title`                   | Optional | `string`       | -              | The title to display in the App Bar.                                                         |
 | `sx`                      | Optional | `object`       | -              | The CSS styles to apply to the component.                                                    |
 
@@ -143,7 +143,7 @@ const ListActions = () => {
 }
 ```
 
-## `aside`: Side Component
+## `aside`
 
 You may want to display additional information on the side of the list. Use the `aside` prop for that, passing the component of your choice:
 
@@ -232,7 +232,7 @@ export const PostList = () => (
 
 **Tip**: the `<Card sx>` prop in the `PostFilterSidebar` component above is here to put the sidebar on the left side of the screen, instead of the default right side.
 
-## `children`: List Layout
+## `children`
 
 `<List>` itself doesn't render the list of records. It delegates this task to its children components. These children components grab the `data` from the `ListContext` and render them on screen.
 
@@ -397,7 +397,7 @@ const Dashboard = () => (
 
 Please note that the selection state is not synced in the URL but in a global store using the resource as key. Thus, all lists in the page using the same resource will share the same selection state. This is a design choice because if row selection is not tied to a resource, then when a user deletes a record it may remain selected without any ability to unselect it. If you want the selection state to be local, you will have to implement your own `useListController` hook and pass a custom key to the `useRecordSelection` hook. You will then need to implement your own `DeleteButton` and `BulkDeleteButton` to manually unselect rows when deleting records.
 
-## `empty`: Empty Page Component
+## `empty`
 
 When there is no result, and there is no active filter, and the resource has a create page, react-admin displays a special page inviting the user to create the first record.
 
@@ -694,7 +694,7 @@ export const PostList = () => (
 );
 ```
 
-## `pagination`: Pagination Component
+## `pagination`
 
 The `pagination` prop allows to replace the default pagination controls by your own.
 
@@ -713,7 +713,7 @@ export const PostList = () => (
 
 See [Paginating the List](./ListTutorial.md#building-a-custom-pagination) for details.
 
-## `perPage`: Pagination Size 
+## `perPage`
 
 By default, the list paginates results by groups of 10. You can override this setting by specifying the `perPage` prop:
 
@@ -801,7 +801,7 @@ export const UsersList = () => (
 );
 ```
 
-## `sort`: Default Sort Field & Order
+## `sort`
 
 Pass an object literal as the `sort` prop to determine the default `field` and `order` used for sorting:
 
@@ -821,13 +821,11 @@ For more details on list sort, see the [Sorting The List](./ListTutorial.md#sort
 
 ## `storeKey`
 
-To display multiple lists of the same resource and keep distinct store states for each of them (filters, sorting and pagination), specify unique keys with the `storeKey` property.
+By default, react-admin stores the list parameters (sort, pagination, filters) in localStorage so that  users can come back to the list and find it in the same state as when they left it. React-admin uses the current resource as the identifier to store the list parameters (under the key `${resource}.listParams`).
 
-In case no `storeKey` is provided, the states will be stored with the following key: `${resource}.listParams`.
+If you want to display multiple lists of the same resource and keep distinct store states for each of them (filters, sorting and pagination), you must give each list a unique `storeKey` property. You can also disable the persistence of list parameters in the store by setting the `storeKey` prop to `false`.
 
-**Note:** Please note that selection state will remain linked to a resource-based key as described [here](./List.md#disablesyncwithlocation).
-
-In the example below, both lists `NewerBooks` and `OlderBooks` use the same resource ('books'), but their controller states are stored separately (under the store keys `'newerBooks'` and `'olderBooks'` respectively). This allows to use both components in the same app, each having its own state (filters, sorting and pagination).
+In the example below, both lists `NewerBooks` and `OlderBooks` use the same resource ('books'), but their list parameters are stored separately (under the store keys `'newerBooks'` and `'olderBooks'` respectively). This allows to use both components in the same app, each having its own state (filters, sorting and pagination).
 
 {% raw %}
 ```jsx
@@ -887,7 +885,7 @@ const Admin = () => {
 
 **Tip:** The `storeKey` is actually passed to the underlying `useListController` hook, which you can use directly for more complex scenarios. See the [`useListController` doc](./useListController.md#storekey) for more info.
 
-You can disable this feature by setting the `storeKey` prop to `false`. When disabled, parameters will not be persisted in the store.
+**Note:** *Selection state* will remain linked to a resource-based key regardless of the `storeKey`. This is a design choice because if row selection is not tied to a resource, then when a user deletes a record it may remain selected without any ability to unselect it. If you want the selection state to be local, you will have to implement your own `useListController` hook and pass a custom key to the `useRecordSelection` hook. You will then need to implement your own `DeleteButton` and `BulkDeleteButton` to manually unselect rows when deleting records.
 
 ## `title`
 
@@ -935,22 +933,6 @@ const PostList = () => (
 
 **Tip**: The `List` component `classes` can also be customized for all instances of the component with its global css name `RaList` as [describe here](https://marmelab.com/blog/2019/12/18/react-admin-3-1.html#theme-overrides)
 
-## Adding `meta` To The DataProvider Call
-
-Use [the `queryOptions` prop](#queryoptions) to pass [a custom `meta`](./Actions.md#meta-parameter) to the `dataProvider.getList()` call.
-
-{% raw %}
-```jsx
-import { List } from 'react-admin';
-
-const PostList = () => (
-    <List queryOptions={{ meta: { foo: 'bar' } }}>
-        ...
-    </List>
-);
-```
-{% endraw %}
-
 ## Infinite Scroll Pagination
 
 By default, the `<List>` component displays the first page of the list of records. To display the next page, the user must click on the "next" button. This is called "finite pagination". An alternative is to display the next page automatically when the user scrolls to the bottom of the list. This is called "infinite pagination".
@@ -1008,37 +990,43 @@ const PostList = () => (
 
 The list will automatically update when a new record is created, or an existing record is updated or deleted.
 
-## How to render an empty list
+## Adding `meta` To The DataProvider Call
 
-You can set the `empty` props value to `false` to bypass the empty page display and render an empty list instead.
+Use [the `queryOptions` prop](#queryoptions) to pass [a custom `meta`](./Actions.md#meta-parameter) to the `dataProvider.getList()` call.
 
-```tsx
+{% raw %}
+```jsx
 import { List } from 'react-admin';
 
-const ProductList = () => (
-    <List empty={false}>
+const PostList = () => (
+    <List queryOptions={{ meta: { foo: 'bar' } }}>
         ...
     </List>
-)
+);
 ```
+{% endraw %}
+
+## Rendering An Empty List
 
-## How to remove the `<ExportButton>`
+When there is no data, react-admin displays a special page inviting the user to create the first record. This page can be customized using [the `empty` prop](#empty-empty-page-component).
 
-You can remove the `<ExportButton>` by passing `false` to the `exporter` prop.
+You can set the `empty` props value to `false` to render an empty list instead.
 
 ```tsx
 import { List } from 'react-admin';
 
 const ProductList = () => (
-    <List exporter={false}>
+    <List empty={false}>
         ...
     </List>
 )
 ```
 
-## How to disable storing the list parameters in the Store
+## Disabling Parameters Persistence
+
+By default, react-admin stores the list parameters (sort, pagination, filters) in localStorage so that  users can come back to the list and find it in the same state as when they left it. This also synchronizes the list parameters across tabs.
 
-You can disable the `storeKey` feature by setting the `storeKey` prop to `false`. When disabled, the list parameters will not be persisted in [the Store](./Store.md).
+You can disable this feature by setting [the `storeKey` prop](#storekey) to `false`:
 
 ```tsx
 import { List } from 'react-admin';

diff --git a/docs/ListBase.md b/docs/ListBase.md
@@ -58,11 +58,11 @@ The `<ListBase>` component accepts the same props as [`useListController`](./use
 * [`exporter`](./List.md#exporter)
 * [`filter`](./List.md#filter-permanent-filter)
 * [`filterDefaultValues`](./List.md#filterdefaultvalues)
-* [`perPage`](./List.md#perpage-pagination-size)
+* [`perPage`](./List.md#perpage)
 * [`queryOptions`](./List.md#queryoptions)
 * [`resource`](./List.md#resource)
-* [`sort`](./List.md#sort-default-sort-field--order)
+* [`sort`](./List.md#sort)
 
 These are a subset of the props accepted by `<List>` - only the props that change data fetching, and not the props related to the user interface.
 
-In addition, `<ListBase>` renders its children components inside a `ListContext`. Check [the `<List children>` documentation](./List.md#children-list-layout) for usage examples.
+In addition, `<ListBase>` renders its children components inside a `ListContext`. Check [the `<List children>` documentation](./List.md#children) for usage examples.
diff --git a/docs/Reference.md b/docs/Reference.md
@@ -65,7 +65,7 @@ title: "Index"
 * [`<EditDialog>`](./EditDialog)<img class="icon" src="./img/premium.svg" />
 * [`<EditInDialogButton>`](./EditInDialogButton.md)<img class="icon" src="./img/premium.svg" />
 * [`<EmailField>`](./EmailField.md)
-* [`<Empty>`](./List.md#empty-empty-page-component)
+* [`<Empty>`](./List.md#empty)
 
 **- F -**
 * [`<FileField>`](./FileField.md)
@@ -121,7 +121,7 @@ title: "Index"
 * [`<NumberInput>`](./NumberInput.md)
 
 **- P -**
-* [`<Pagination>`](./List.md#pagination-pagination-component)
+* [`<Pagination>`](./List.md#pagination)
 * [`<PasswordInput>`](./PasswordInput.md)
 * [`<PreferencesSetter>`](https://marmelab.com/ra-enterprise/modules/ra-preferences#preferencessetter-setting-preferences-declaratively)<img class="icon" src="./img/premium.svg" />
 

diff --git a/docs/ReferenceField.md b/docs/ReferenceField.md
@@ -190,6 +190,53 @@ The `<ReferenceField>` component accepts the usual `className` prop. You can als
 
 To override the style of all instances of `<ReferenceField>` using the [Material UI style overrides](https://mui.com/material-ui/customization/theme-components/#theme-style-overrides), use the `RaReferenceField` key.
 
+## Performance
+
+When used in a `<Datagrid>`, `<ReferenceField>` fetches the referenced record only once for the entire table. 
+
+![ReferenceField](./img/reference-field.png)
+
+For instance, with this code:
+
+```jsx
+import { List, Datagrid, ReferenceField, TextField, EditButton } from 'react-admin';
+
+export const PostList = () => (
+    <List>
+        <Datagrid>
+            <TextField source="id" />
+            <ReferenceField label="User" source="user_id" reference="users" />
+            <TextField source="title" />
+            <EditButton />
+        </Datagrid>
+    </List>
+);
+```
+
+React-admin accumulates and deduplicates the ids of the referenced records to make *one* `dataProvider.getMany()` call for the entire list, instead of n `dataProvider.getOne()` calls. So for instance, if the API returns the following list of posts:
+
+```js
+[
+    {
+        id: 123,
+        title: 'Totally agree',
+        user_id: 789,
+    },
+    {
+        id: 124,
+        title: 'You are right my friend',
+        user_id: 789
+    },
+    {
+        id: 125,
+        title: 'Not sure about this one',
+        user_id: 735
+    }
+]
+```
+
+Then react-admin renders the `<PostList>` with a loader for the `<ReferenceField>`, fetches the API for the related users in one call (`dataProvider.getMany('users', { ids: [789,735] }`), and re-renders the list once the data arrives. This accelerates the rendering and minimizes network load.
+
 ## Rendering More Than One Field
 
 You often need to render more than one field of the reference table (e.g. if the `users` table has a `first_name` and a `last_name` field).
@@ -255,54 +302,7 @@ export const PostShow = () => (
 );
 ```
 
-## Performance
-
-When used in a `<Datagrid>`, `<ReferenceField>` fetches the referenced record only once for the entire table. 
-
-![ReferenceField](./img/reference-field.png)
-
-For instance, with this code:
-
-```jsx
-import { List, Datagrid, ReferenceField, TextField, EditButton } from 'react-admin';
-
-export const PostList = () => (
-    <List>
-        <Datagrid>
-            <TextField source="id" />
-            <ReferenceField label="User" source="user_id" reference="users" />
-            <TextField source="title" />
-            <EditButton />
-        </Datagrid>
-    </List>
-);
-```
-
-React-admin accumulates and deduplicates the ids of the referenced records to make *one* `dataProvider.getMany()` call for the entire list, instead of n `dataProvider.getOne()` calls. So for instance, if the API returns the following list of posts:
-
-```js
-[
-    {
-        id: 123,
-        title: 'Totally agree',
-        user_id: 789,
-    },
-    {
-        id: 124,
-        title: 'You are right my friend',
-        user_id: 789
-    },
-    {
-        id: 125,
-        title: 'Not sure about this one',
-        user_id: 735
-    }
-]
-```
-
-Then react-admin renders the `<PostList>` with a loader for the `<ReferenceField>`, fetches the API for the related users in one call (`dataProvider.getMany('users', { ids: [789,735] }`), and re-renders the list once the data arrives. This accelerates the rendering and minimizes network load.
-
-## Removing the link
+## Removing The Link
 
 You can prevent `<ReferenceField>` from adding a link to its children by setting `link` to `false`.
 

diff --git a/docs/ReferenceOneField.md b/docs/ReferenceOneField.md
@@ -224,7 +224,7 @@ const BookShow = () => (
 ```
 {% endraw %}
 
-## Removing the link
+## Removing The Link
 
 By default, `<ReferenceOneField>` links to the edition page of the related record. You can disable this behavior by setting the `link` prop to `false`.