Document web components based MFE functionality (#1708)

docs/luigi-ux-features.md

@@ -87,8 +87,8 @@ Alternatively, to keep the loading indicator until the first micro frontend is u
 
 ## Collapsed left side navigation
 
-If you use **responsiveNavigation = 'semiCollapsible'**  or **'Fiori3'** mode in your settings, you can adjust collapsed state of the left side navigation by using the **collapseLeftSideNav** function. 
+If you use **responsiveNavigation = 'semiCollapsible'**  or **'Fiori3'** mode in your settings, you can adjust collapsed state of the left side navigation by using the **collapseLeftSideNav** function.
 
 * To close the left side navigation, execute **Luigi.ux().collapseLeftSideNav(true)** in Luigi Core once your initial micro frontend has finished loading. It will set the collapsed state to `true` in **Local Storage**. Which closes the left side navgation, by showing only icons.
 
-* Set the value to `false` if you want to make left side navigation to be open.
+* Set the value to `false` if you want to open left side navigation.

docs/navigation-parameters-reference.md

@@ -114,6 +114,18 @@ Check our [Advanced Scenarios](advanced-scenarios.md) page for an example.
   - **action**(string): defines an operation, i.e.: `display`, `approve` or `edit`. The operation is intended to be performed on a **semanticObject** such as a sales order or a certain product. It can only contain alphanumerical characters but also the underscore character.
   - **pathSegment**(string): represents the target of the navigation. In order to use it as a target link, it has to be defined under navigation nodes in the Luigi configuration.
 
+### validWebcomponentUrls
+  - **type**: array
+  - **description**: a list of allowed web component URLs. They must be added as regular expressions to the array.
+  - **example**:
+```javascript
+settings: {
+  navigation: {
+    validWebcomponentUrls:[
+      'https\:\/\/YOURPROJECT\.gitlab\.io\/.?'
+    ]
+  }
+```
 
 ## Node parameters
 Node parameters are all the parameters that can be added to an individual navigation node in the `nodes:` section of the Luigi configuration file.
@@ -372,6 +384,165 @@ settings: {
 - **description**: overrides the default behaviour of categories whether multiple categories can be collapsed. When set to `true`, only one category is collapsed. The navigation is similar to an accordion; when the user clicks another category the previously collapsed category is closed and the new one is opened. Note that this will be applied to its direct children.
 - **default**: `false`
 
+### webcomponent
+- **type**: boolean OR object
+- **description**: mark a node as web component either by setting this attribute to `true` or defining an object with the attributes described below. In the latter case, the `viewUrl` attribute of the node must point to the web component `.js` file.
+- **attributes**:
+  - **id**: unique id of the web component
+  - **type**: string, like `module`.
+  - **selfRegistered**: if it is `true`, the web component bundle will be added via script tag.
+  - **tagName**: tag name where web component is added to DOM. 
+- **since**: 1.7.0
+
+### compound
+- **type**: object
+- **description**: It is possible to compound web components in one micro frontend. Within this object, the layout of the web components can be defined. In addition, you can configure nested web components. In that case the parent web component has to be defined by a slot with a name to plug in the child web component. For example `<header><slot name="header">header</slot></header>`.
+Web components can communicate over an event bus.
+- **attributes**:
+  - **renderer**:
+    - **type**: object
+    - **description**: meta information about the layout of the compound web components
+    - **attributes**:
+      - **use**:
+        - **type**: string OR object
+        - **description**: You can define a CSS layout, like the CSS `grid`, or implement an extended layout by defining an object using the `extends` property. In that case you have the possibility to implement the following functions to manipulate the standard renderer.
+        - **attributes**:
+          - **extends**
+            - **type**: string, e.g. `grid`
+            - **description**: 
+          - **createCompoundContainer**
+            - **type**: function
+            - **description**: This function gets the grid layout `config` object as parameter. 
+          - **createCompoundItemContainer**
+            - **type**: function
+            - **description** This function gets a the grid layout `config` object and the layout config object for the item.
+          - **attachCompoundItem**
+            - **type**: function
+            - **description** This function allows you to attach custom HTML to the item. This function gets the whole HTML container of the compound items and the item container as parameter.
+      - **config**:
+        - **type**: object
+        - **description**: defines the configuration object of the grid layout
+        - **attributes**:
+          - **columns**: represents the css `grid-template-columns`, e.g `1fr 2fr` .
+          - **rows**: represents the css `grid-template-rows`, e.g. `150px 150px`.
+          - **gap**: represents the css `grid-gap`, e.g. `auto`.
+          - **min-height** min height
+          - **layouts**
+            - **type**: array
+            - **description**: defines the configuration objects of the grid layout for media queries.
+            - **attributes**:
+              - **columns**: represents the css `grid-template-columns`, e.g `1fr 2fr` .
+              - **rows**: represents the css `grid-template-rows`, e.g. `150px 150px`.
+              - **gap**: represents the css `grid-gap`, e.g. `auto`.
+              - **min-width** min width
+              - **max-width** max width
+  - **children**
+    - **type**: array
+    - **description**: Array of web component nodes.
+    - **attributes**:
+      - **id**: unique `id` of the web component.
+      - **viewUrl**: URL which points to the web component `.js` file.
+      - **context**: object, which you can pass to the web component.
+      - **layoutConfig**: config object to define the position of an item in a grid. The properties are `row` and `column` and get the same values as in the CSS grid standard. If you want to use the mechanism of nested web components, you can define a `slot` property with the slot name instead of the config object. In that case this web component node will be plugged in the parent web component.
+      - **eventListeners**
+        - **type**: array
+        - **description**: array of events.
+        - **attributes**:
+          - **source**: `id` of the web component, which you want to listen. Alternatively you can set an asterisk, e.g. `*`
+          - **name**: name of the event, which this web component is listening to.
+          - **action**: type of the event, such as `update`.
+          - **dataConverter**
+            - **type** function
+            - **description** This function gets the data object as parameter. If the received data are in a different format, you can use this function to convert the data.
+- **example**:
+```javascript
+{
+    pathSegment: 'webcomponent',
+    label: 'Webcomponent',
+    icon: 'along-stacked-chart',
+    loadingIndicator: {
+      enabled: false
+    },
+    context: {
+      title: 'Hello WebComponent!'
+    },
+    viewUrl: '/helloWorldWC.js',
+    webcomponent: true,
+    openNodeInModal: true
+  },
+```
+
+Below is Luigi's web component example configuration which shows 3 web components in a grid layout. It also includes the configuration for the event bus. The `input` web component sends the typed input. The `header` web component listens to a `sendInput` event from a web component with the id `input1`. Received data will be converted. An `update` event will be triggered, changing the `header` web component where an `update` event listener is registered.
+
+```javascript
+{
+        pathSegment: 'wc_grid',
+        label: 'Grid',
+        category: {
+          label: 'Compound',
+          icon: 'attachment-html',
+          collapsible: true
+        },
+        compound: {
+          renderer:
+          {
+            use: 'grid',
+            config: {
+              columns: '1fr 1fr 1fr',
+              /*rows: '150px',*/
+              /*gap: '30px',*/
+              layouts: [{
+                minWidth: 0,
+                maxWidth: 600,
+                columns: '1fr',
+                gap: 0
+              }, {
+                minWidth: 600,
+                maxWidth: 1024,
+                columns: '1fr 1fr',
+                gap: '30px'
+              }]
+            }
+          },
+          children: [{
+            viewUrl: 'URL_TO_HEADER_WEBCOMPONENT/panelHeader.js',
+            context: {
+              title: 'My Awesome Grid',
+              description: 'Really awesome'
+            },
+            layoutConfig: {
+              row: "1",
+              column: "1 / -1"
+            },
+            eventListeners: [{
+              source: 'input1',
+              name: 'sendInput',
+              action: 'update',
+              dataConverter: (data) => {
+                return 'new text: ' + data;
+              }
+            }]
+          }, {
+            id: 'input1',
+            viewUrl: 'URL_TO_SOME_WEBCOMPONENT/input.js',
+            context: {
+              title: 'Some input test',
+              instant: true
+            }
+          },
+          {
+            viewUrl: 'URL_TO_FOOTER_WEBCOMPONENT/panelFooter.js',
+            context: {
+              footer: 'This is the end of awesomeness'
+            },
+            layoutConfig: {
+              column: "1 / -1"
+            }
+          }]
+        }
+      }
+```
+- **since**: 1.7.0
 
 ## Context switcher