From ef441dcc75050abba45ae05316ea429dc23c70ba Mon Sep 17 00:00:00 2001
From: adrien guernier <adrien@marmelab.com>
Date: Tue, 12 Sep 2023 17:28:44 +0200
Subject: [PATCH 1/2] [Doc] Introduce improve ReferenceManyToManyInput doc

---
 docs/ReferenceManyToManyInput.md | 312 +++++++++++++++++++++++++++++--
 1 file changed, 301 insertions(+), 11 deletions(-)

diff --git a/docs/ReferenceManyToManyInput.md b/docs/ReferenceManyToManyInput.md
index 8d1218b8ea4..9a9935bd6e7 100644
--- a/docs/ReferenceManyToManyInput.md
+++ b/docs/ReferenceManyToManyInput.md
@@ -5,7 +5,7 @@ title: "The ReferenceManyToManyInput Component"
 
 # `<ReferenceManyToManyInput>`
 
-This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component allows to create, edit or remove relationships between two resources sharing an associative table. The changes in the associative table are sent to the dataProvider when the user submits the form, so that they can cancel the changes before submission.
+This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component allows to create, edit or remove relationships between two resources sharing an associative table. The changes in the associative table are sent to the dataProvider _when the user submits the form_, so that they can cancel the changes before submission.
 
 <video controls autoplay playsinline muted loop width="100%">
   <source src="./img/reference-many-to-many-input.webm" type="video/webm" />
@@ -13,7 +13,13 @@ This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" s
   Your browser does not support the video tag.
 </video>
 
-In this example, `bands.id` matches `performances.band_id`, and `performances.venue_id` matches `venues.id`:
+**Note**: The `<ReferenceManyToManyInput>` cannot currently display multiple records with the same id from the end reference resource even though they might have different properties in the associative table.
+
+Check [the `ra-relationships` Enterprise documentation](https://marmelab.com/ra-enterprise/modules/ra-relationships#referencemanytomanyinput).
+
+## Usage
+
+For instance, here is how to edit the `venues` related to an `bands` record through a `performances` associative table.
 
 ```
 ┌─────────┐       ┌──────────────┐      ┌───────────────┐
@@ -26,16 +32,11 @@ In this example, `bands.id` matches `performances.band_id`, and `performances.ve
 └─────────┘       └──────────────┘      └───────────────┘
 ```
 
-The form displays the venues name in a [`<AutocompleteArrayInput>`](./AutocompleteArrayInput.md):
+In this example, `bands.id` matches `performances.band_id`, and `performances.venue_id` matches `venues.id`. The form displays the venues name in a `<AutocompleteArrayInput>`:
 
-```jsx
+```tsx
 import React from 'react';
-import {
-    AutocompleteArrayInput,
-    Edit,
-    SimpleForm,
-    TextInput,
-} from 'react-admin';
+import { Edit, AutocompleteArrayInput, SimpleForm, TextInput } from 'react-admin';
 import { ReferenceManyToManyInput } from '@react-admin/ra-relationships';
 
 export const BandEdit = () => (
@@ -57,4 +58,293 @@ export const BandEdit = () => (
 );
 ```
 
-Check [the `ra-relationships` documentation](https://marmelab.com/ra-enterprise/modules/ra-relationships#referencemanytomanyinput) for more details.
+`<ReferenceManyToManyInput>` expects an input allowing to select multiple values as child - like `<AutocompleteArrayInput>` in the example above. Other possible children are `<SelectArrayInput>`, `<CheckboxGroupInput>`, and `<DualListInput>`.
+
+## Props
+
+| Prop             | Required | Type                                        | Default                            | Description                                                                                                                                                                                                       |
+| ---------------- | -------- | ------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`       | Required | `element`                                   | -                                  | A select array input element (e.g. `<SelectArrayInput>`).                                                                                                                                                         |
+| `filter`         | Optional | `object`                                    | `{}`                               | Filter for the associative table (passed to the `getManyReference()` call)                                                                                                                                        |
+| `filterChoices`  | Optional | `object`                                    | `{}`                               | Filter for the possible choices fetched from the reference table (passed to the `getList()` call)                                                                                                                 |
+| `perPage`        | Optional | `number`                                    | 25                                 | Limit for the number of results fetched from the associative table                                                                                                                                                |
+| `perPageChoices` | Optional | `number`                                    | 25                                 | Limit for the number of possible choices fetched from the reference table                                                                                                                                         |
+| `reference`      | Required | `string`                                    | -                                  | Name of the reference resource, e.g. 'venues'                                                                                                                                                                    |
+| `sort`           | Optional | `{ field: string, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }`   | Sort for the associative table (passed to the `getManyReference()` call)                                                                                                                                          |
+| `sortChoices`    | Optional | `{ field: string, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }`   | Sort for the possible choices fetched from the reference table (passed to the `getList()` call)                                                                                                                   |
+| `source`         | Optional | `string`                                    | `'id'`                             | Name of the field containing the identity of the main resource. Used determine the value to look for in the associative table.                                                                                    |
+| `through`        | Required | `string`                                    | -                                  | Name of the resource for the associative table, e.g. 'book_authors'                                                                                                                                               |
+| `using`          | Optional | `string`                                    | `'([resource]_id,[reference]_id)'` | Tuple (comma separated) of the two field names used as foreign keys, e.g 'book_id,author_id'. The tuple should start with the field pointing to the resource, and finish with the field pointing to the reference |
+
+## `children`
+
+`<ReferenceManyToManyInput>` expects an _select_ component as child, i.e. a component working inside a `ChoiceContext`. That means you can use a [`<SelectArrayInput>`](./SelectArrayInput.md), or a [`<AutocompleteArrayInput>`](./AutocompleteArrayInput.md). For instance, to allow user choses `performances` through a `<SelectArrayInput>`: 
+
+```diff
+import React from 'react';
+- import { Edit, AutocompleteArrayInput, SimpleForm, TextInput } from 'react-admin';
++ import { Edit, SelectArrayInput, SimpleForm, TextInput } from 'react-admin';
+import { ReferenceManyToManyInput } from '@react-admin/ra-relationships';
+
+export const BandEdit = () => (
+    <Edit>
+        <SimpleForm>
+            <TextInput source="name" />
+            <ReferenceManyToManyInput
+                resource="bands"
+                reference="venues"
+                through="performances"
+                using="band_id,venue_id"
+            >
+-                <AutocompleteArrayInput
+-                    label="Performances"
+-                    optionText="name"
+-                />
++            <SelectArrayInput label="Performances" />
+            </ReferenceManyToManyInput>
+        </SimpleForm>
+    </Edit>
+);
+```
+
+## `filter`
+
+You can filter the records of the associative table (eg: `performances`) using the `filter` prop. This `filter` is passed to the `getManyReference()` call.
+
+{% raw %}
+```tsx
+<ReferenceManyToManyInput
+    reference="venues"
+    through="performances"
+    using="band_id,venue_id"
+    filter={{ date: '2018-08-31' }}
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+{% endraw %}
+
+## `filterChoices`
+You can also filter the records of the reference table (eg: `venues`) using the `filterChoice` prop. This `filterChoice` is passed to the `getList()` call.
+
+{% raw %}
+```tsx
+<ReferenceManyToManyInput
+    reference="venues"
+    through="performances"
+    using="band_id,venue_id"
+    filterChoice={{ location: 'New York' }}
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+{% endraw %}
+
+## `perPage`
+
+By default, react-admin displays 25 entries from the associative table (eg: 25 `performances`). You can change the limit by setting the `perPage` prop:
+
+```tsx
+<ReferenceManyToManyInput
+    reference="venues"
+    through="performances"
+    using="band_id,venue_id"
+    perPage={10}
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+
+## `perPageChoices`
+
+By default, react-admin displays 25 entries from the reference table (eg: 25 `venues`). You can change the limit by setting the `perPageChoices` prop:
+
+```tsx
+<ReferenceManyToManyInput
+    reference="venues"
+    through="performances"
+    using="band_id,venue_id"
+    perPageChoices={10}
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+## `reference`
+
+The name of the target resource to fetch.
+
+For instance, if you want to display the venues of a given bands, through performances, the reference name should be venues:
+
+```tsx
+<ReferenceManyToManyInput
+    source="id"
+    reference="venues"
+    resource="bands"
+    through="performances"
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+## `sort`
+
+By default, react-admin orders the possible values by `id` desc for the associative table (eg: `performances`). You can change this order by setting the `sort` prop (an object with `field` and `order` properties) to be applied to the associative resource.
+
+{% raw %}
+```tsx
+<ReferenceManyToManyInput
+    reference="venues"
+    through="performances"
+    using="band_id,venue_id"
+    sort={{ field: 'id', order: 'DESC' }}
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+{% endraw %}
+
+## `sortChoices`
+
+By default, react-admin orders the possible values by `id` desc for the reference table (eg: `venues`). You can change this order by setting the `sortChoices` prop (an object with `field` and `order` properties) to be applied to the reference resource.
+
+{% raw %}
+```tsx
+<ReferenceManyToManyInput
+    reference="venues"
+    through="performances"
+    using="band_id,venue_id"
+    sortChoices={{ field: 'id', order: 'DESC' }}
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+{% endraw %}
+
+## `source`
+
+By default, ReferenceManyToManyField uses the `id` field as target for the reference. If the foreign key points to another field of your record, you can select it with the source prop
+
+```tsx
+<ReferenceManyToManyInput
+    source="_id"
+    reference="venues"
+    resource="bands"
+    through="performances"
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+
+## `through`
+
+You can specify the associative table name using the `through` prop.
+
+```tsx
+<ReferenceManyToManyInput reference="venues" through="performances">
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+
+## `using`
+
+You can specify the associative table columns using the `using` prop.
+
+```tsx
+<ReferenceManyToManyInput
+    reference="venues"
+    through="performances"
+    using="band_id,venue_id"
+>
+    {/* ... */}
+</ReferenceManyToManyInput>
+```
+
+## DataProvider Calls
+
+When rendered, `<ReferenceManyToManyInput>` fetches the `dataProvider` three times in a row:
+
+-   once to get the records of the associative resource (`performances` in this case), using a `getManyReference()` call
+-   once to get the records of the reference resource (`venues` in this case), using a `getMany()` call.
+-   once to get the possible values of the reference resource (`venues` in this case) to show as suggestions in the input, using a `getList()` call
+
+For instance, if the user edits the band of id `123`, `<ReferenceManyToManyInput>` first issues the following query to the `dataProvider`:
+
+```js
+dataProvider.getManyReference('venues', {
+    target: 'band_id',
+    id: 123,
+});
+```
+
+Let's say that the `dataProvider` returns the following response:
+
+```json
+{
+    "data": [
+        { "id": 667, "band_id": 123, "venue_id": 732 },
+        { "id": 895, "band_id": 123, "venue_id": 874 }
+        { "id": 901, "band_id": 123, "venue_id": 756 }
+    ],
+    "total": 3
+}
+```
+
+Then, `<ReferenceManyToManyInput>` issues a second query to the `dataProvider`:
+
+```js
+dataProvider.getMany('venues', {
+    ids: [732, 874, 756],
+});
+```
+
+Which returns the following:
+
+```json
+{
+    "data": [
+        { "id": 732, "name": "Madison Square Garden" },
+        { "id": 874, "name": "Yankee Stadium" }
+        { "id": 874, "name": "Barclays Center" }
+    ]
+}
+```
+
+That's enough to display the current value in the input. But to display venues suggestions, the component makes a final call:
+
+```js
+dataProvider.getList('venues', {
+    sort: { field: 'id', order: 'DESC' },
+    pagination: { page: 1, perPage: 25 },
+    filter: {},
+});
+```
+
+```json
+{
+    "data": [
+        { "id": 732, "name": "Madison Square Garden" },
+        { "id": 874, "name": "Yankee Stadium" }
+        { "id": 874, "name": "Barclays Center" }
+        ...
+    ],
+    "total": 32
+}
+```
+
+And that's it for the display phase.
+
+When the user submits the form, the `save` function compares the value of the `<ReferenceManyToManyInput>` (the list of relationships edited by the user) with the value previously returned by the `dataProvider`. Using a diffing algorithm, it deduces a list of **insertions** and **deletions** in the associative table, that are executed all at once.
+
+For instance, let's say that after displaying the venues 732 and 874 where bands 123 performs, the user removes venue 732, and adds venues 2 and 3. Upon submission, the `dataProvider` will detect removals and additions, and send the following queries:
+
+```js
+dataProvider.delete('performances', {
+    id: 667,
+    previousData: { id: 667, band_id: 123, venue_id: 732 },
+});
+dataProvider.create('performances', {
+    data: { band_id: 123, venue_id: 2 },
+});
+dataProvider.create('performances', {
+    data: { band_id: 123, venue_id: 3 },
+});
+```
\ No newline at end of file

From 97837f198dfc7283fcd33c01b8c2cc409137cfee Mon Sep 17 00:00:00 2001
From: fzaninotto <fzaninotto@gmail.com>
Date: Tue, 12 Sep 2023 19:07:33 +0200
Subject: [PATCH 2/2] Review

---
 docs/ReferenceManyToManyInput.md | 47 ++++++++++++++++++--------------
 1 file changed, 27 insertions(+), 20 deletions(-)

diff --git a/docs/ReferenceManyToManyInput.md b/docs/ReferenceManyToManyInput.md
index 9a9935bd6e7..481be310c72 100644
--- a/docs/ReferenceManyToManyInput.md
+++ b/docs/ReferenceManyToManyInput.md
@@ -15,11 +15,9 @@ This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" s
 
 **Note**: The `<ReferenceManyToManyInput>` cannot currently display multiple records with the same id from the end reference resource even though they might have different properties in the associative table.
 
-Check [the `ra-relationships` Enterprise documentation](https://marmelab.com/ra-enterprise/modules/ra-relationships#referencemanytomanyinput).
-
 ## Usage
 
-For instance, here is how to edit the `venues` related to an `bands` record through a `performances` associative table.
+Let's imagine that you're writing an app managing concerts for artists. The data model features a many-to-many relationship between the `bands` and `venues` tables through a `performances` associative table.
 
 ```
 ┌─────────┐       ┌──────────────┐      ┌───────────────┐
@@ -32,7 +30,9 @@ For instance, here is how to edit the `venues` related to an `bands` record thro
 └─────────┘       └──────────────┘      └───────────────┘
 ```
 
-In this example, `bands.id` matches `performances.band_id`, and `performances.venue_id` matches `venues.id`. The form displays the venues name in a `<AutocompleteArrayInput>`:
+In this example, `bands.id` matches `performances.band_id`, and `performances.venue_id` matches `venues.id`. 
+
+To let users edit the `venues` for given `band` in an `<AutocompleteArrayInput>`, wrap that input in a `<ReferenceManyToManyInput>` where you define the relationship via the `reference`, `through` and `using` props:
 
 ```tsx
 import React from 'react';
@@ -58,27 +58,29 @@ export const BandEdit = () => (
 );
 ```
 
-`<ReferenceManyToManyInput>` expects an input allowing to select multiple values as child - like `<AutocompleteArrayInput>` in the example above. Other possible children are `<SelectArrayInput>`, `<CheckboxGroupInput>`, and `<DualListInput>`.
+`<ReferenceManyToManyInput>` expects a child that is an input allowing to select multiple values as child - like `<AutocompleteArrayInput>` in the example above. Other possible children are `<SelectArrayInput>`, `<CheckboxGroupInput>`, and `<DualListInput>`.
 
 ## Props
 
 | Prop             | Required | Type                                        | Default                            | Description                                                                                                                                                                                                       |
 | ---------------- | -------- | ------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `children`       | Required | `element`                                   | -                                  | A select array input element (e.g. `<SelectArrayInput>`).                                                                                                                                                         |
+| `reference`      | Required | `string`                                    | -                                  | Name of the reference resource, e.g. 'venues'                                                                                                                                                                    |
+| `through`        | Required | `string`                                    | -                                  | Name of the resource for the associative table, e.g. 'book_authors'                                                                                                                                               |
 | `filter`         | Optional | `object`                                    | `{}`                               | Filter for the associative table (passed to the `getManyReference()` call)                                                                                                                                        |
-| `filterChoices`  | Optional | `object`                                    | `{}`                               | Filter for the possible choices fetched from the reference table (passed to the `getList()` call)                                                                                                                 |
+| `filter Choices`  | Optional | `object`                                    | `{}`                               | Filter for the possible choices fetched from the reference table (passed to the `getList()` call)                                                                                                                 |
 | `perPage`        | Optional | `number`                                    | 25                                 | Limit for the number of results fetched from the associative table                                                                                                                                                |
-| `perPageChoices` | Optional | `number`                                    | 25                                 | Limit for the number of possible choices fetched from the reference table                                                                                                                                         |
-| `reference`      | Required | `string`                                    | -                                  | Name of the reference resource, e.g. 'venues'                                                                                                                                                                    |
+| `perPage Choices` | Optional | `number`                                    | 25                                 | Limit for the number of possible choices fetched from the reference table                                                                                                                                         |
 | `sort`           | Optional | `{ field: string, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }`   | Sort for the associative table (passed to the `getManyReference()` call)                                                                                                                                          |
-| `sortChoices`    | Optional | `{ field: string, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }`   | Sort for the possible choices fetched from the reference table (passed to the `getList()` call)                                                                                                                   |
+| `sort Choices`    | Optional | `{ field: string, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }`   | Sort for the possible choices fetched from the reference table (passed to the `getList()` call)                                                                                                                   |
 | `source`         | Optional | `string`                                    | `'id'`                             | Name of the field containing the identity of the main resource. Used determine the value to look for in the associative table.                                                                                    |
-| `through`        | Required | `string`                                    | -                                  | Name of the resource for the associative table, e.g. 'book_authors'                                                                                                                                               |
 | `using`          | Optional | `string`                                    | `'([resource]_id,[reference]_id)'` | Tuple (comma separated) of the two field names used as foreign keys, e.g 'book_id,author_id'. The tuple should start with the field pointing to the resource, and finish with the field pointing to the reference |
 
 ## `children`
 
-`<ReferenceManyToManyInput>` expects an _select_ component as child, i.e. a component working inside a `ChoiceContext`. That means you can use a [`<SelectArrayInput>`](./SelectArrayInput.md), or a [`<AutocompleteArrayInput>`](./AutocompleteArrayInput.md). For instance, to allow user choses `performances` through a `<SelectArrayInput>`: 
+`<ReferenceManyToManyInput>` expects an _select_ component as child, i.e. a component working inside a `ChoiceContext`. That means you can use a [`<SelectArrayInput>`](./SelectArrayInput.md), or a [`<AutocompleteArrayInput>`](./AutocompleteArrayInput.md). 
+
+For instance, to allow user to choose `performances` using a `<SelectArrayInput>` instead of an `<AutocompleteArrayInput>`, you can write:
 
 ```diff
 import React from 'react';
@@ -109,7 +111,7 @@ export const BandEdit = () => (
 
 ## `filter`
 
-You can filter the records of the associative table (eg: `performances`) using the `filter` prop. This `filter` is passed to the `getManyReference()` call.
+You can filter the records of the associative table (e.g. `performances`) using the `filter` prop. This `filter` is passed to the `getManyReference()` call.
 
 {% raw %}
 ```tsx
@@ -125,7 +127,10 @@ You can filter the records of the associative table (eg: `performances`) using t
 {% endraw %}
 
 ## `filterChoices`
-You can also filter the records of the reference table (eg: `venues`) using the `filterChoice` prop. This `filterChoice` is passed to the `getList()` call.
+
+`<ReferenceManyToManyInput>` displays a list of possible values from the reference table (e.g. `venues`) as suggestions in the input. It uses the `getList()` dataProvider call to fetch these possible values.
+
+You can filter the possible values of the reference table using the `filterChoices` prop. This `filterChoices` is passed to the `getList()` call.
 
 {% raw %}
 ```tsx
@@ -142,7 +147,7 @@ You can also filter the records of the reference table (eg: `venues`) using the
 
 ## `perPage`
 
-By default, react-admin displays 25 entries from the associative table (eg: 25 `performances`). You can change the limit by setting the `perPage` prop:
+By default, react-admin displays at most 25 entries from the associative table (e.g. 25 `performances`). You can change the limit by setting the `perPage` prop:
 
 ```tsx
 <ReferenceManyToManyInput
@@ -157,7 +162,9 @@ By default, react-admin displays 25 entries from the associative table (eg: 25 `
 
 ## `perPageChoices`
 
-By default, react-admin displays 25 entries from the reference table (eg: 25 `venues`). You can change the limit by setting the `perPageChoices` prop:
+`<ReferenceManyToManyInput>` displays a list of possible values from the reference table (e.g. `venues`) as suggestions in the input. It uses the `getList()` dataProvider call to fetch these possible values.
+
+By default, react-admin displays at most 25 possible values from the reference table (e.g. 25 `venues`). You can change the limit by setting the `perPageChoices` prop:
 
 ```tsx
 <ReferenceManyToManyInput
@@ -187,7 +194,7 @@ For instance, if you want to display the venues of a given bands, through perfor
 ```
 ## `sort`
 
-By default, react-admin orders the possible values by `id` desc for the associative table (eg: `performances`). You can change this order by setting the `sort` prop (an object with `field` and `order` properties) to be applied to the associative resource.
+By default, react-admin orders the possible values by `id` desc for the associative table (e.g. `performances`). You can change this order by setting the `sort` prop (an object with `field` and `order` properties) to be applied to the associative resource.
 
 {% raw %}
 ```tsx
@@ -204,7 +211,7 @@ By default, react-admin orders the possible values by `id` desc for the associat
 
 ## `sortChoices`
 
-By default, react-admin orders the possible values by `id` desc for the reference table (eg: `venues`). You can change this order by setting the `sortChoices` prop (an object with `field` and `order` properties) to be applied to the reference resource.
+By default, react-admin orders the possible values by `id` desc for the reference table (e.g. `venues`). You can change this order by setting the `sortChoices` prop (an object with `field` and `order` properties).
 
 {% raw %}
 ```tsx
@@ -221,7 +228,7 @@ By default, react-admin orders the possible values by `id` desc for the referenc
 
 ## `source`
 
-By default, ReferenceManyToManyField uses the `id` field as target for the reference. If the foreign key points to another field of your record, you can select it with the source prop
+By default, ReferenceManyToManyField uses the `id` field as target for the reference. If the foreign key points to another field of your record, you can select it with the `source` prop:
 
 ```tsx
 <ReferenceManyToManyInput
@@ -236,7 +243,7 @@ By default, ReferenceManyToManyField uses the `id` field as target for the refer
 
 ## `through`
 
-You can specify the associative table name using the `through` prop.
+You must specify the associative table name using the `through` prop.
 
 ```tsx
 <ReferenceManyToManyInput reference="venues" through="performances">
@@ -246,7 +253,7 @@ You can specify the associative table name using the `through` prop.
 
 ## `using`
 
-You can specify the associative table columns using the `using` prop.
+You can specify the columns to use in the associative using the `using` prop.
 
 ```tsx
 <ReferenceManyToManyInput