overridable: breaking change and deprecation notices, dynamicParametrize usage for both built-in and custom fields

Author: palkerecsenyi

docs/operate/customize/look-and-feel/override_components.md

@@ -18,16 +18,21 @@ For this guide, we assume that you are familiar with React and JavaScript.
 The UI of InvenioRDM is composed of classic HTML web pages for mostly static content, and React web apps for very dynamic content to enhance the user experience.
 While a [dedicated guide](./templates.md) describes how to override HTML web pages (Jinja templates), this guide focus on how to override React components.
 
-InvenioRDM uses the React library [`react-overridable`](https://github.com/indico/react-overridable). The library provides a mechanism to mark React components as "overridable" by id.
-Developers can define a map `{ id: Overridden React component }`, which is then applied when each React component is rendered: the overridden component is rendered instead of the default one.
+InvenioRDM uses the React library [`react-overridable`](https://github.com/indico/react-overridable). The library provides a mechanism to mark React components as "overridable" by ID.
+Developers can define a mapping which is then applied when each React component is rendered.
+The override can be specified in one of three ways:
+
+- completely replacing a component with a custom one
+- a static override of the props passed to the component
+- a 'dynamic' override of the props based on the form's state
 
 As example for this guide, you will learn how to override the UI React component **in the upload form that marks a record as "Metadata only"**. More specifically, you will replace the "Metadata-only record" checkbox with a toggle, a "switch-like" component.
 
 ![Metadata-only record checkbox](./imgs/metadata_only_checkbox.png)
 
-## Steps
+## Guided example
 
-### Identify how to override
+### 1. Identify which component to override
 
 At the moment, the easiest way to understand how to identify if the component that you want to override is a classic HTML component or a React component is to use the Developer Tools in your browser (e.g. [Chrome](https://developer.chrome.com/docs/devtools/) or [Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/)). You can inspect the code and take advantage of some useful [React browser extensions](https://beta.reactjs.org/learn/react-developer-tools) to select and inspect elements:
 
@@ -37,7 +42,7 @@ You can then find the component in the InvenioRDM modules source code, searching
 
 You can always [ask for help](../../../install/troubleshoot.md#getting-help)!
 
-### Find the React Overridable ID
+### 2. Find the React Overridable ID
 
 The easiest way to to find the ID of an overridable component is to use `react-overridable`'s built-in developer tool.
 Simply open a browser console on your local instance and call the global function `reactOverridableEnableDevMode()`.
@@ -46,11 +51,11 @@ You can click a tag to copy its ID to your clipboard.
 
 ![Metadata-only checkbox overridable ID in an overlay](./imgs/metadata_id_overlay.png)
 
-The React component's overridable ID for the '`Metadata-only record`' checkbox component is `ReactInvenioDeposit.FileUploaderToolbar.MetadataOnlyToggle.container`. It can be found in the [`invenio-rdm-records`](https://github.com/inveniosoftware/invenio-rdm-records/blob/dd72962b713f07b81699f7d5c9a8a673d585466a/invenio_rdm_records/assets/semantic-ui/js/invenio_rdm_records/src/deposit/fields/FileUploader/FileUploaderToolbar.js#L56) module.
+The React component's overridable ID for the '`Metadata-only record`' checkbox component is `InvenioRdmRecords.DepositForm.FileUploaderToolbar.MetadataOnlyToggle`. It can be found in the [`invenio-rdm-records`](https://github.com/inveniosoftware/invenio-rdm-records/blob/dd72962b713f07b81699f7d5c9a8a673d585466a/invenio_rdm_records/assets/semantic-ui/js/invenio_rdm_records/src/deposit/fields/FileUploader/FileUploaderToolbar.js#L56) module.
 
-### The mapping file
+### 3. Find or create the mapping file
 
-In a new InvenioRDM v11 or above installations, an almost empty file named `mapping.js` is available at the following path in your `assets` folder:
+In new InvenioRDM v11 or above installations, a near-empty file named `mapping.js` is available at the following path in your `assets` folder:
 
 ```terminal
 ├── assets
@@ -68,7 +73,7 @@ export const overriddenComponents = {};
 
 The `const overriddenComponents` is the map that will contain all your future overridden components.
 
-### New component creation
+### 4. Create a new component creation
 
 Let's create a new React component, very similar to the default `FileUploaderToolbar`, changing the UI component that will render. In the same file `mapping.js`, add the following code above the `const overriddenComponents`:
 
@@ -109,7 +114,7 @@ Now, change the map by adding your new component:
 ...
 
 export const overriddenComponents = {
-  "ReactInvenioDeposit.FileUploaderToolbar.MetadataOnlyToggle.container": MetadataToggle,
+  "InvenioRdmRecords.DepositForm.FileUploaderToolbar.MetadataOnlyToggle": MetadataToggle,
 };
 ```
 
@@ -125,18 +130,122 @@ When navigating to the upload form, you should now see your new React component
 
 !["`Metadata-only record`" toggle](./imgs/metadata_only_toggle.png)
 
+## Overriding props only
+
+In many cases, you simply want to make a small modification to a component by changing one of its props instead of recreating the component from scratch by yourself.
+This can either be done by specifying the desired prop overrides statically, or by expressing them as a function of the form state.
+
+### Static
+
+You can use the `parametrize` function built into `react-overridable`, into which you need to pass the component you wish to override and an object containing your props.
+These props will be 'merged' with the existing props, with yours taking precedence over existing ones of the same name.
+
+```javascript
+import { parametrize } from "react-overridable"
+import { TitlesField } from "@js/invenio_rdm_records"
+
+export const overriddenComponents = {
+  "InvenioRdmRecords.DepositForm.TitlesField": parametrize(
+    TitlesField,
+    {
+      helpText: "Describe your resource in a few words"
+    }
+  )
+}
+```
+
+### Dynamic
+
+To implement more complex functionality in the deposit form, you can override the props of components by using a custom function.
+This allows you to express a range of behaviours:
+
+- hiding fields that are inapplicable to a certain resource type
+- changing the label of fields to be more contextually relevant
+- marking a field as disabled when its value has been made obvious by the value of another field
+- showing certain fields only when a specific community is selected
+- etc.
+
+For this, you can use the `dynamicParametrize` function in `react-invenio-forms`, which behaves similarly to `parametrize`.
+The callback you pass will be evaluated whenever the form state changes, and the object you return will override the props
+passed to the component.
+
+```javascript
+import { dynamicParametrize } from "react-invenio-forms"
+import { RelatedWorksField } from "@js/invenio_rdm_records"
+
+export const overriddenComponents = {
+  "InvenioRdmRecords.DepositForm.TitlesField": dynamicParametrize(
+    TitlesField,
+    ({ formValues }) => {
+      return {
+        helpText: `Enter the title of your ${formValue.metadata.resource_type}`
+      }
+    }
+  )
+}
+```
+
+The callback function is currently passed an object as its single argument, containing the following values:
+
+- `formValues`: the raw values of the entire deposit form as given by Formik. The majority of field values are under the `metadata` key.
+- `existingProps`: the props passed to the element before your override.
+
+### Deposit form field props
+
+The built-in fields in the deposit form (e.g. title, description, etc.) have a number of common props to make customizing basic functionality easier.
+
+The following props may be overriden on all built-in fields:
+
+- `label`: the user-facing short label
+- `labelIcon`: the ID of the [Semantic UI Icon](https://semantic-ui.com/elements/icon.html) to include in the label
+- `helpText`: a small optional text generally shown below the field, providing additional context to the user
+- `placeholder`: same as the [HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/placeholder)
+
+Additionally, the following props may be overriden on fields that are not mandatory. 
+At the moment, this is all fields except the Resource Type, Title, Publication Date, and Creatibutors.
+
+- `hidden`: if `true`, the field is not rendered at all
+    - If a field already had a value before being hidden, this will still be included in the model and will be sent to the server when the form is submitted.
+    - Fields retain their values when they are hidden and later re-shown.
+- `disabled`: same as the [HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/disabled)
+- `required`: if `true`, shows a red asterisk in the field label
+    - This does not affect the form validation model on the frontend or the backend, and is purely a stylistic setting.
+
+Many fields have their own props in addition to these. 
+Please [view the source code](https://github.com/inveniosoftware/invenio-rdm-records/tree/master/invenio_rdm_records/assets/semantic-ui/js/invenio_rdm_records/src/deposit/fields) for more details.
+
 ## Other examples
 
-Let's hide completely the '`Metadata-only record`'checkbox from the upload form.
+### Showing/hiding
+
+You can completely hide a field in the deposit form, based on either a static `true`/`false` value or in response to the current state of the form.
 
-It is possible to remove a component using the overridable strategy. In the previous example, instead of declaring a target component `MetadataToggle` you can simply change the map to:
+To simply permanently hide the field, you can use something like this:
 
 ```javascript
 export const overriddenComponents = {
-  "ReactInvenioDeposit.FileUploaderToolbar.MetadataOnlyToggle.container": () => null,
+  "InvenioRdmRecords.DepositForm.RelatedWorksField": () => null,
 };
 ```
 
-The expression `() => null` above is defining an "empty" component, thus removing it from the upload form.
+The expression `() => null` above is defining an "empty" component, thus removing it from the deposit form.
+
+To dynamically only show the field when the `image` resource type is selected, you can use the `dynamicParametrize` function.
+
+```javascript
+import { dynamicParametrize } from "react-invenio-forms"
+import { RelatedWorksField } from "@js/invenio_rdm_records"
+
+export const overriddenComponents = {
+  "InvenioRdmRecords.DepositForm.RelatedWorksField": dynamicParametrize(
+    TitlesField,
+    ({ formValues }) => {
+      return {
+        hidden: formValues.metadata.resource_type !== "image"
+      }
+    }
+  )
+}
+```
 
 In order to see more examples in action, you can check the [zenodo-rdm](https://github.com/zenodo/zenodo-rdm) repository!

docs/operate/customize/metadata/custom_fields/widgets.md

@@ -28,6 +28,36 @@ These props are applicable to all widgets. In the reference below, only props ad
 
     To improve consistency with the fields in the deposit form, the `icon` prop has been renamed to `labelIcon` and `description` has been renamed to `helpText`. The functionality of these props is unchanged and the old names will continue working for now, albeit with a deprecation notice.
 
+## Dynamic behaviour
+
+While controlling the static prop values via the [`RDM_CUSTOM_FIELDS_UI` config value](records.md#upload-deposit-form) is relatively straightforward, it doesn't allow
+you to specify dynamic behaviour, such as showing/hiding the field only in specific cases, or using a different `helpText` depending on the resource type.
+
+This can instead be done using the `dynamicParametrize` function.
+For more details on its usage, [see the documentation on overriding React components](../../look-and-feel/override_components.md#dynamic).
+
+The ID of the overridable is the internal name of your custom field (e.g. `cern:experiment`).
+You can override any of the props listed on this page (except `fieldPath`), depending on the specific widget.
+
+For example, to make the `cern:experiment` field only be shown for thesis records:
+
+```javascript
+// my-rdm-instance/assets/js/invenio_app_rdm/overridableRegistry/mapping.js
+
+import { dynamicParametrize, Input } from "react-invenio-forms"
+
+export const overriddenComponents = {
+  "cern:experiment": dynamicParametrize(
+    Input,
+    ({ formValues }) => {
+      return {
+        hidden: formValues.metadata.resource_type !== "thesis"
+      }
+    }
+  )
+}
+```
+
 ## Input
 
 An input field for a single string value.

docs/releases/vNext/upgrade-vNext.md

@@ -172,10 +172,22 @@ affected by `invenio index destroy --yes-i-know` and are totally functional afte
 
 ### Required changes
 
+#### Overridable IDs in the deposit form
+
+To improve consistency in naming conventions and structure, some IDs of Overridables in the deposit form have been modified. If you are overriding any of these components, you will need to change the ID in your mapping file to reflect these modifications.
+
+The full list of ID changes [can be found here](https://github.com/inveniosoftware/invenio-rdm-records/pull/2101/files#diff-ff3c479edefad986d2fe6fe7ead575a46b086e3bbcf0ccc86d85efc4a4c63c79).
+
+If you are not overriding any of these components, you do not need to change anything.
+
 ### Optional changes
 
 #### Deprecations
 
+##### Custom field widget prop names
+
+Many [custom field widgets](../../operate/customize/metadata/custom_fields/widgets.md) used the `icon` and `description` props, which have now been deprecated and replaced with `labelIcon` and `helpText` respectively. This is to improve consistency with the naming of the built-in fields used in the deposit form and thereby avoid confusion. The old names will continue to function for now, but we recommend updating to the new names where applicable.
+
 #### New configuration variables
 
 These are the new configuration variables introduced in this release. Make sure that you read the related documentation before enabling them. Add them to your `invenio.cfg` as needed:

docs/releases/vNext/version-vNext.md

@@ -26,10 +26,11 @@ Here is a quick summary of the myriad of other improvements in this release:
 
 ## Deprecations
 
-
+- Many [custom field widgets](../../operate/customize/metadata/custom_fields/widgets.md) used the `icon` and `description` props, which have now been deprecated and replaced with `labelIcon` and `helpText` respectively. This is to improve consistency with the naming of the built-in fields used in the deposit form and thereby avoid confusion. The old names will continue to function for now.
 
 ## Breaking changes
 
+- Overridables in the deposit form have been modified to improve consistency in structure and naming conventions. This has involved renaming the IDs of several `<Overridable>`s, but none have been removed. If you are using these IDs to override components, please see [the full list of updates](https://github.com/inveniosoftware/invenio-rdm-records/pull/2101/files#diff-ff3c479edefad986d2fe6fe7ead575a46b086e3bbcf0ccc86d85efc4a4c63c79) and change your IDs accordingly.
 
 ## Requirements