marmelab · hiaselhans · Mar 18, 2024 · Mar 19, 2024 · Mar 19, 2024 · Mar 19, 2024
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,20 @@
 # Changelog
 
+## v4.16.15
+
+* Fix `useGetIdentity` regression ([#9756](https://github.com/marmelab/react-admin/pull/9756)) ([djhi](https://github.com/djhi))
+* Bump vite from 3.2.8 to 3.2.10 ([#9755](https://github.com/marmelab/react-admin/pull/9755)) ([dependabot[bot]](https://github.com/apps/dependabot))
+
+## v4.16.14
+
+* Fix `<FilterButton>` does not support the variant prop ([#9751](https://github.com/marmelab/react-admin/9751)) by ([adguernier](https://github.com/marmelab/adguernier))
+* [Demo] Fix error when viewing newly created deals in CRM demo ([#9733](https://github.com/marmelab/react-admin/9733)) by ([erwanMarmelab](https://github.com/marmelab/erwanMarmelab))
+* Bump express from 4.17.3 to 4.19.2 ([#9747](https://github.com/marmelab/react-admin/9747)) by ([dependabot](https://github.com/marmelab/dependabot))
+* Bump webpack-dev-middleware from 6.1.1 to 6.1.2 ([#9739](https://github.com/marmelab/react-admin/9739)) by ([dependabot](https://github.com/marmelab/dependabot))
+* [Doc] Update `<RichTextInput>` to explain how to access the editor object ([#9731](https://github.com/marmelab/react-admin/9731)) by ([erwanMarmelab](https://github.com/marmelab/erwanMarmelab))
+* [Doc] Update "Writing a Data Provider" chapter to include test advice ([#9738](https://github.com/marmelab/react-admin/9738)) by ([fzaninotto](https://github.com/marmelab/fzaninotto))
+* [Doc] Update RBAC to mention ability to define permissions on an array of resources ([#9729](https://github.com/marmelab/react-admin/9729)) by ([erwanMarmelab](https://github.com/marmelab/erwanMarmelab))
+
 ## v4.16.13
 
 * Fix `<AutocompleteInput createLabel>` ([#9712](https://github.com/marmelab/react-admin/pull/9712)) ([fzaninotto](https://github.com/fzaninotto))

diff --git a/cypress/package.json b/cypress/package.json
@@ -10,6 +10,6 @@
         "cypress": "^10.9.0",
         "cypress-plugin-tab": "^1.0.5",
         "cypress-vite": "^1.4.0",
-        "express": "~4.17.3"
+        "express": "~4.19.2"
     }
 }
diff --git a/docs/AuthProviderList.md b/docs/AuthProviderList.md
@@ -8,7 +8,7 @@ title: "Supported Auth Provider Backends"
 It's very common that your auth logic is so specific that you'll need to write your own `authProvider`. However, the community has built a few open-source Auth Providers that may fit your need:
 
 <div class="providers-list" markdown="1">
-- ![auth0 Logo](./img/backend-logos/auth0.svg "auth0 Logo")**[Auth0](https://auth0.com/)**: [marmelab/ra-auth-auth0](https://github.com/marmelab/ra-auth-auth0/blob/main/packages/ra-auth-auth0/Readme.md)
+- ![auth0 Logo](./img/backend-logos/auth0.svg "auth0 Logo")**[Auth0 by Okta](https://auth0.com/)**: [marmelab/ra-auth-auth0](https://github.com/marmelab/ra-auth-auth0/blob/main/packages/ra-auth-auth0/Readme.md)
 - ![amplify Logo](./img/backend-logos/amplify.svg "amplify Logo")**[AWS Amplify](https://docs.amplify.aws)**: [MrHertal/react-admin-amplify](https://github.com/MrHertal/react-admin-amplify)
 - ![cognito Logo](./img/backend-logos/aws.png "cognito Logo")**[AWS Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/setting-up-the-javascript-sdk.html)**: [marmelab/ra-auth-cognito](https://github.com/marmelab/ra-auth-cognito/blob/main/packages/ra-auth-cognito/Readme.md)
 - ![azure Logo](./img/backend-logos/microsoft.svg "azure Logo")**[Azure Active Directory (using MSAL)](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser)**: [marmelab/ra-auth-msal](https://github.com/marmelab/ra-auth-msal/blob/main/packages/ra-auth-msal/Readme.md) ([Tutorial](https://marmelab.com/blog/2023/09/13/active-directory-integration-tutorial.html))

diff --git a/docs/AuthRBAC.md b/docs/AuthRBAC.md
@@ -98,6 +98,7 @@ Here are a few examples of permissions:
 
 - `{ action: "*", resource: "*" }`: allow everything
 - `{ action: "read", resource: "*" }`: allow read actions on all resources
+- `{ action: "read", resource: ["companies", "people"] }`: allow read actions on a subset of resources
 - `{ action: ["read", "create", "edit", "export"], resource: "companies" }`: allow all actions except delete on companies
 - `{ action: ["write"], resource: "game.score", record: { "id": "123" } }`: allow to change the score on a particular game
 

diff --git a/docs/Create.md b/docs/Create.md
@@ -561,6 +561,8 @@ Note: In order to get the `mutationOptions` being considered, you have to set th
 
 ## Linking Two Inputs
 
+<iframe src="https://www.youtube-nocookie.com/embed/YkqjydtmfcU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen style="aspect-ratio: 16 / 9;width:100%;margin-bottom:1em;"></iframe>
+
 Edition forms often contain linked inputs, e.g. country and city (the choices of the latter depending on the value of the former).
 
 React-admin relies on [react-hook-form](https://react-hook-form.com/) for form handling. You can grab the current form values using react-hook-form's [useWatch](https://react-hook-form.com/docs/usewatch) hook.

diff --git a/docs/DataProviderWriting.md b/docs/DataProviderWriting.md
@@ -7,6 +7,9 @@ title: "Writing A Data Provider"
 
 APIs are so diverse that quite often, none of [the available Data Providers](./DataProviderList.md) suit you API. In such cases, you'll have to write your own Data Provider. Don't worry, it usually takes only a couple of hours. 
 
+<iframe src="https://www.youtube-nocookie.com/embed/sciDJAUEu_M" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen style="aspect-ratio: 16 / 9;width:100%;margin-bottom:1em;"></iframe>
+
+
 The methods of a Data Provider receive a request, and return a promise for a response. Both the request and the response format are standardized.
 
 ## Data Provider Methods
@@ -150,7 +153,7 @@ dataProvider.getMany('posts', { ids: [123, 124, 125] })
 
 ## `getManyReference`
 
-React-admin calls `dataProvider.getManyReference()` to fetch several records related to another one.
+React-admin calls `dataProvider.getManyReference()` to fetch the records related to another record. Although similar to `getList`, this method is designed for relationships. It is necessary because some APIs require a different query to fetch related records (e.g. `GET /posts/123/comments` to fetch comments related to post 123).
 
 **Interface**
 
@@ -425,6 +428,30 @@ export default {
 };
 ```
 
+## Handling Authentication
+
+Your API probably requires some form of authentication (e.g. a token in the `Authorization` header). It's the responsibility of [the `authProvider`](./Authentication.md) to log the user in and obtain the authentication data. React-admin doesn't provide any particular way of communicating this authentication data to the Data Provider. Most of the time, storing the authentication data in the  `localStorage` is the best choice - and allows uses to open multiple tabs without having to log in again.
+
+Check the [Handling Authentication](./DataProviders.md#handling-authentication) section in the Data Providers introduction for an example of such a setup.
+
+## Testing Data Provider Methods
+
+A good way to test your data provider is to build a react-admin app with components that depend on it. Here is a list of components calling the data provider methods:
+
+| Method             | Components |
+| ------------------ | --------- |
+| `getList`          | [`<List>`](./List.md), [`<ListGuesser>`](./ListGuesser.md), [`<ListBase>`](./ListBase.md), [`<InfiniteList>`](./InfiniteList.md), [`<Count>`](./Count.md), [`<Calendar>`](./Calendar.md), [`<ReferenceInput>`](./ReferenceInput.md), [`<ReferenceArrayInput>`](./ReferenceArrayInput.md), [`<ExportButton>`](./Buttons.md#exportbutton), [`<PrevNextButtons>`](./PrevNextButtons.md) |
+| `getOne`           | [`<Show>`](./Show.md), [`<ShowGuesser>`](./ShowGuesser.md), [`<ShowBase>`](./ShowBase.md), [`<Edit>`](./Edit.md), [`<EditGuesser>`](./EditGuesser.md), [`<EditBase>`](./EditBase.md) |
+| `getMany`          | [`<ReferenceField>`](./ReferenceField.md), [`<ReferenceArrayField>`](./ReferenceArrayField.md), [`<ReferenceInput>`](./ReferenceInput.md), [`<ReferenceArrayInput>`](./ReferenceArrayInput.md) |
+| `getManyReference` | [`<ReferenceManyField>`](./ReferenceManyField.md), [`<ReferenceOneField>`](./ReferenceOneField.md), [`<ReferenceManyInput>`](./ReferenceManyInput.md), [`<ReferenceOneInput>`](./ReferenceOneInput.md) |
+| `create`           | [`<Create>`](./Create.md), [`<CreateBase>`](./CreateBase.md), [`<EditableDatagrid>`](./EditableDatagrid.md), [`<CreateInDialogButton>`](./CreateInDialogButton.md) |
+| `update`           | [`<Edit>`](./Edit.md), [`<EditGuesser>`](./EditGuesser.md), [`<EditBase>`](./EditBase.md), [`<EditableDatagrid>`](./EditableDatagrid.md), [`<EditInDialogButton>`](./EditInDialogButton.md), [`<UpdateButton>`](./UpdateButton.md) |
+| `updateMany`       | [`<BulkUpdateButton>`](./BulkUpdateButton.md) |
+| `delete`           | [`<DeleteButton>`](./DeleteButton.md), [`<EditableDatagrid>`](./EditableDatagrid.md) |
+| `deleteMany`       | [`<BulkDeleteButton>`](./BulkDeleteButton.md) |
+
+A simple react-admin app with one `<Resource>` using [guessers](./Features.md#guessers--scaffolding) for the `list`, `edit`, and `show` pages is a good start.
+
 ## The `meta` Parameter
 
 All data provider methods accept a `meta` parameter. React-admin core components never set this `meta` when calling the data provider. It's designed to let you pass additional parameters to your data provider.
@@ -465,6 +492,44 @@ const { data } = dataProvider.getOne('posts', { id: 123 })
 
 This will cause the Edit view to blink on load. If you have this problem, modify your Data Provider to return the same shape for all methods. 
 
+## `fetchJson`: Built-In HTTP Client
+
+Although your Data Provider can use any HTTP client (`fetch`, `axios`, etc.), react-admin suggests using a helper function called `fetchJson` that it provides.
+
+`fetchJson` is a wrapper around the `fetch` API that automatically handles JSON deserialization, rejects when the HTTP response isn't 2XX or 3XX, and throws a particular type of error that allows the UI to display a meaningful notification. `fetchJson` also lets you add an `Authorization` header if you pass a `user` option.
+
+Here is how you can use it in your Data Provider:
+
+```diff
++import { fetchUtils } from 'react-admin';
+
++const fetchJson = (url, options = {}) => {
++   options.user = {
++       authenticated: true,
++       // use the authentication token from local storage (given the authProvider added it there)
++       token: localStorage.getItem('token')
++   };
++   return fetchUtils.fetchJson(url, options);
++};
+// ...
+
+const dataProvider = {
+    getList: (resource, params) => {
+        const { page, perPage } = params.pagination;
+        const { field, order } = params.sort;
+        const query = {
+            sort: JSON.stringify([field, order]),
+            range: JSON.stringify([(page - 1) * perPage, page * perPage - 1]),
+            filter: JSON.stringify(params.filter),
+        };
+        const url = `${apiUrl}/${resource}?${stringify(query)}`;
+-       return fetch(url, { method: 'GET' });
++       return fetchJson(url, { method: 'GET' });
+    },
+    // ...
+};
+```
+
 ## Example REST Implementation
 
 Let's say that you want to map the react-admin requests to a REST backend exposing the following API:

diff --git a/docs/Edit.md b/docs/Edit.md
@@ -728,6 +728,8 @@ The user will see alerts when other users update or delete the record.
 
 ## Linking Two Inputs
 
+<iframe src="https://www.youtube-nocookie.com/embed/YkqjydtmfcU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen style="aspect-ratio: 16 / 9;width:100%;margin-bottom:1em;"></iframe>
+
 Edition forms often contain linked inputs, e.g. country and city (the choices of the latter depending on the value of the former).
 
 React-admin relies on [react-hook-form](https://react-hook-form.com/) for form handling. You can grab the current form values using react-hook-form's [useWatch](https://react-hook-form.com/docs/usewatch) hook.

diff --git a/docs/Form.md b/docs/Form.md
@@ -292,6 +292,8 @@ Check [the `<AutoSave>` component](./AutoSave.md) documentation for more details
 
 ## Linking Two Inputs
 
+<iframe src="https://www.youtube-nocookie.com/embed/YkqjydtmfcU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen style="aspect-ratio: 16 / 9;width:100%;margin-bottom:1em;"></iframe>
+
 Edition forms often contain linked inputs, e.g. country and city (the choices of the latter depending on the value of the former).
 
 React-admin relies on [react-hook-form](https://react-hook-form.com/) for form handling. You can grab the current form values using react-hook-form's [useWatch](https://react-hook-form.com/docs/usewatch) hook.

diff --git a/docs/JsonSchemaForm.md b/docs/JsonSchemaForm.md
@@ -7,6 +7,18 @@ title: "JsonSchemaForm"
 
 This [Enterprise Edition](https://marmelab.com/ra-enterprise)<img class="icon" src="./img/premium.svg" /> component allows to render a form from a JSON Schema description based on [react-jsonschema-form](https://github.com/rjsf-team/react-jsonschema-form).
 
+## Usage
+
+First, install the `@react-admin/ra-json-schema-form` package:
+
+```sh
+npm install --save @react-admin/ra-json-schema-form
+# or
+yarn add @react-admin/ra-json-schema-form
+```
+
+If you have a JSON Schema description of your form based on [react-jsonschema-form](https://github.com/rjsf-team/react-jsonschema-form), you can use the `<JsonSchemaForm>` component to render it.
+
 For instance, to generate the following form:
 
 ![JsonSchemaForm](https://marmelab.com/ra-enterprise/modules/assets/jsonschemaform.webp)
@@ -15,56 +27,130 @@ Configure the `<Edit>` view with a `<JsonSchemaForm>` child as follows:
 
 {% raw %}
 ```jsx
-import { Edit } from "react-admin";
-import { JsonSchemaForm } from "@react-admin/ra-json-schema-form";
+import { Edit } from 'react-admin';
+import { JsonSchemaForm } from '@react-admin/ra-json-schema-form';
+
+const CustomerEdit = () => (
+    <Edit>
+        <JsonSchemaForm
+            schema={{
+                type: 'object',
+                properties: {
+                    id: { type: 'number' },
+                    first_name: { type: 'string', title: 'First name' },
+                    last_name: { type: 'string', minLength: 3 },
+                    dob: { type: 'string', format: 'date' },
+                    sex: { type: 'string', enum: ['male', 'female'] },
+                    employer_id: { type: 'number' },
+                    occupations: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                name: { type: 'string' },
+                                from: { type: 'string', format: 'date' },
+                                to: { type: 'string', format: 'date' },
+                            },
+                        },
+                    },
+                },
+                required: ['id', 'last_name', 'employer_id'],
+            }}
+            uiSchema={{
+                id: { 'ui:disabled': true },
+                employer_id: {
+                    'ui:widget': 'reference',
+                    'ui:options': {
+                        reference: 'employers',
+                        optionText: 'name',
+                    },
+                },
+            }}
+            onChange={change =>
+                process.env.NODE_ENV !== 'test' &&
+                console.log('changed', change)
+            }
+            onError={error =>
+                process.env.NODE_ENV !== 'test' && console.log('error', error)
+            }
+        />
+    </Edit>
+);
+```
+{% endraw %}
+
+`<JsonSchemaForm>` initializes the form with the current `record`, and renders it like `<SimpleForm>` does.
+
+It expects a `schema` prop describing the expected data shape, and a `uiSchema` prop describing the UI.
+
+`<JsonSchemaForm>` is a wrapper around JsonSchema Form's `<Form>` component, so please refer to [JsonSchema Form's documentation](https://react-jsonschema-form.readthedocs.io/en/latest/#usage) for detailed usage.
+
+## UI Widgets
+
+`<JsonSchemaForm>` comes with the following UI widgets:
+
+For `boolean` fields:
+
+-   `checkbox` (default)
+-   `radio`
+-   `select`
+
+For `string` fields:
+
+-   `text` (default)
+-   `textarea`
+-   `password`
+-   `color`
+
+The built-in `string` field also supports the `format` property, and will render an appropriate widget depending on its value:
+
+-   `email`: renders an `input[type=email]` element;
+-   `uri`: renders an `input[type=url]` element;
+-   `data-url`: Renders an `input[type=file]` element (if the string is part of an array, multiple files will be handled automatically);
+-   `date`: Renders an `input[type=date]` element;
+-   `date-time`: Renders an `input[type=datetime-local]` element.
+
+For `number` and `integer` fields, you can also specify the `format` to render an alternative widget:
+
+-   `text` (default)
+-   `updown`
+-   `range`
+-   `radio`
+
+`ra-json-schema-form` comes with the an additional UI widget for `string` fields: `reference`. It's the equivalent of [react-admin's `<ReferenceInput>` component](https://marmelab.com/react-admin/ReferenceInput.html). It fetches the foreign key, and uses a relationship to populate the list of options.
+
+Specify the `reference`, `optionText`, and other options through the `ui:options` UI schema directive:
+
+{% raw %}
+```tsx
+import { Edit } from 'react-admin';
+import { JsonSchemaForm } from '@react-admin/ra-json-schema-form';
 
 const CustomerEdit = () => (
-  <Edit>
-    <JsonSchemaForm
-      schema={{
-        type: "object",
-        properties: {
-          id: { type: "number" },
-          first_name: { type: "string", title: "First name" },
-          last_name: { type: "string", minLength: 3 },
-          dob: { type: "string", format: "date" },
-          sex: { type: "string", enum: ["male", "female"] },
-          employer_id: { type: "number" },
-          occupations: {
-            type: "array",
-            items: {
-              type: "object",
-              properties: {
-                name: { type: "string" },
-                from: { type: "string", format: "date" },
-                to: { type: "string", format: "date" },
-              },
-            },
-          },
-        },
-        required: ["id", "last_name", "employer_id"],
-      }}
-      uiSchema={{
-        id: { "ui:disabled": true },
-        employer_id: {
-          "ui:widget": "reference",
-          "ui:options": {
-            reference: "employers",
-            optionText: "name",
-          },
-        },
-      }}
-      onChange={(change) =>
-        process.env.NODE_ENV !== "test" && console.log("changed", change)
-      }
-      onError={(error) =>
-        process.env.NODE_ENV !== "test" && console.log("error", error)
-      }
-    />
-  </Edit>
+    <Edit>
+        <JsonSchemaForm
+            schema={{
+                type: 'object',
+                properties: {
+                    id: { type: 'number' },
+                    employer_id: { type: 'number' },
+                },
+            }}
+            uiSchema={{
+                employer_id: {
+                    'ui:widget': 'reference',
+                    'ui:options': {
+                        reference: 'employers',
+                        optionText: 'name',
+                    },
+                },
+            }}
+        />
+    </Edit>
 );
 ```
 {% endraw %}
 
-Check [the `ra-json-schema-form` documentation](https://marmelab.com/ra-enterprise/modules/ra-json-schema-form#installation) for more details.
+## I18N
 
+`<JsonSchemaForm>` passes all labels, descriptions and errors to react-admin's `translate` function. You can translate the form by providing custom translations via your `i18nProvider`.