overridable: rearrange guide page

* Rearranged the content of `override_components.md` according to
suggestions from @fenekku

Author: palkerecsenyi

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

@@ -2,10 +2,10 @@
 
 *Introduced in InvenioRDM v11*
 
-This documentation is targeted to developers who want to customize specific UI React components in an instance.
+This documentation is targeted at developers who want to customize specific UI React components in an instance.
 For this guide, we assume that you are familiar with React and JavaScript.
 
-## Override React components
+## About overriding
 
 !!! warning "Experimental feature"
 
@@ -18,44 +18,34 @@ 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.
+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, which is implemented for many components across the InvenioRDM codebase.
 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.
+## 1. Find the component to override
 
-![Metadata-only record checkbox](./imgs/metadata_only_checkbox.png)
-
-## Guided example
-
-### 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:
+At the moment, the easiest way 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 the [React Developer Tools](https://react.dev/learn/react-developer-tools) browser extension to select and inspect elements:
 
 ![React browser extension example](./imgs/react_browser_extension_example.png)
 
-You can then find the component in the InvenioRDM modules source code, searching it in your local development environment or using the search feature in GitHub in the [inveniosoftware organization](https://github.com/search?q=org%3Ainveniosoftware+FileUploaderToolbar&type=code).
-
-You can always [ask for help](../../../install/troubleshoot.md#getting-help)!
+If the component shows up in the React tree, it is a React component and can be overriden using the methods described on this page.
+Otherwise, it is an HTML component that can be [overriden using Jinja templates](./templates.md).
 
-### 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.
+Next, you can find the ID of an overridable component using `react-overridable`'s built-in developer tool.
 Simply open a browser console on your local instance and call the global function `reactOverridableEnableDevMode()`.
 All overridable components will display a small red overlay tag showing their ID.
 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 `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.
+You can search the ID in the [`inveniosoftware` organisation on GitHub](https://github.com/inveniosoftware/) to find the component and its props, which
+can be helpful when overriding.
+
+If you're struggling, you can always [ask for help](../../../install/troubleshoot.md#getting-help)!
 
-### 3. Find or create the mapping file
+## 2. Find or create the mapping file
 
-In new InvenioRDM v11 or above installations, a near-empty file named `mapping.js` is available at the following path in your `assets` folder:
+In new InvenioRDM installations at v11 or above, a near-empty file named `mapping.js` is available at the following path in your `assets` folder:
 
 ```terminal
 ├── assets
@@ -71,75 +61,24 @@ For existing installations, you will have to create it. It is a very simple file
 export const overriddenComponents = {};
 ```
 
-The `const overriddenComponents` is the map that will contain all your future overridden components.
-
-### 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`:
+The `const overriddenComponents` is the map that will contain all your future overrides.
 
-```javascript
-  import React from "react";
-  import { Checkbox } from "semantic-ui-react";
-  import { useFormikContext } from "formik";
-  import PropTypes from "prop-types";
-
-  const MetadataToggle = (props) => {
-    const { filesEnabled } = props;
-    const { setFieldValue } = useFormikContext();
-
-    const handleOnChangeMetadataOnly = () => {
-      setFieldValue("files.enabled", !filesEnabled);
-      setFieldValue("access.files", "public");
-    };
-
-    return (
-      <Checkbox
-        toggle
-        label="Metadata-only record"
-        onChange={handleOnChangeMetadataOnly}
-      />
-    );
-  };
+## 3. Override the component
 
-  export default MetadataToggle;
-
-  MetadataToggle.propTypes = {
-    filesEnabled: PropTypes.bool.isRequired,
-  };
-```
-
-Now, change the map by adding your new component:
-
-```javascript
-...
-
-export const overriddenComponents = {
-  "InvenioRdmRecords.DepositForm.FileUploaderToolbar.MetadataOnlyToggle": MetadataToggle,
-};
-```
-
-Lastly, rebuild your assets and run the instance:
-
-```terminal
-cd my-site
-invenio-cli assets build
-invenio-cli run
-```
+The override can be specified in one of three ways, depending on your use case and the amount of control you require:
 
-When navigating to the upload form, you should now see your new React component instead of the default:
-
-!["`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.
+- a static override of the props passed to the component
+- a 'dynamic' override of the props based on the form's state
+- completely replacing a component with a custom one
 
-### Static
+### a. Statically override a component's props
 
 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.
 
+In this case, the props are defined once in your `mapping.js` file and are not updated during the runtime of the application.
+You are also unable to access any React/Formik context while defining the props.
+
 ```javascript
 import { parametrize } from "react-overridable"
 import { TitlesField } from "@js/invenio_rdm_records"
@@ -154,7 +93,7 @@ export const overriddenComponents = {
 }
 ```
 
-### Dynamic
+### b. Dynamically override a component's props
 
 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:
@@ -190,7 +129,54 @@ The callback function is currently passed an object as its single argument, cont
 - `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
+### c. Fully replace a component
+
+To fully replace a component with your custom one, first create the component definition within your instance's source code.
+For example:
+
+```jsx
+import React from "react";
+import { Checkbox } from "semantic-ui-react";
+import { useFormikContext } from "formik";
+import PropTypes from "prop-types";
+
+const MetadataToggle = (props) => {
+  const { filesEnabled } = props;
+  const { setFieldValue } = useFormikContext();
+
+  const handleOnChangeMetadataOnly = () => {
+    setFieldValue("files.enabled", !filesEnabled);
+    setFieldValue("access.files", "public");
+  };
+
+  return (
+    <Checkbox
+      toggle
+      label="Metadata-only record"
+      onChange={handleOnChangeMetadataOnly}
+    />
+  );
+};
+
+export default MetadataToggle;
+
+MetadataToggle.propTypes = {
+  filesEnabled: PropTypes.bool.isRequired,
+};
+```
+
+Now, change the map by adding your new component:
+
+```javascript
+...
+
+export const overriddenComponents = {
+  "InvenioRdmRecords.DepositForm.FileUploaderToolbar.MetadataOnlyToggle": MetadataToggle,
+};
+```
+
+
+## Common field props in the deposit form
 
 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.
 
@@ -202,7 +188,7 @@ The following props may be overriden on all built-in fields:
 - `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.
+At the moment, this is all fields except 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.
@@ -214,7 +200,7 @@ At the moment, this is all fields except the Resource Type, Title, Publication D
 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
+## Examples
 
 ### Showing/hiding