# Xena WebComponents

This project is part of [the new strategy for further development of the current Xena UI](https://egjira.atlassian.net/wiki/spaces/XNA/pages/908132353/Future+Classic+Xena+UI+Development).

It is a wrapper project for exposing lazyloaded modules as webcomponents for use in Xena. It allows for developing parts of the Xena UI in Angular and use them in the existing Xena UI as webcomponents with the smallest possible bundle size possible for each view. This is done by making sure that we:

* only load the parts needed for the specific view in Xena and only WHEN needed.
* load the Angular codebase only once.
* combine all modules in one build to ensure we benefit the most from tree-shaking.

It is strongly encouraged to use(and enhance) the [Xena Design System](https://ds.xena.biz) for **[dumb components](https://medium.com/@thejasonfile/dumb-components-and-smart-components-e7b33a698d43)** (button, dropdowns, inputs etc.) - both in Angular components and in the existing Xena UI. This will further shrink the overall bundle size of the page as the same dumb-components can be reused and hence loaded only once.

The following diagram shows how it comes together:

![Diagram of Xena WebComponents in combination with Xena Core UI](src/assets/Proposal.png)

## Getting started developing
In order to install all packages, you need to have a valid personal access token for your Github profile ready. This is because this project depends on @eg-brs/eg.ng.element which is hosted together with its repo on Github. The personal access token needs only to be able to read packages. When you have it ready, this is how you do:

1. Create/Edit your ~/.npmrc (`~` means you home folder, for Windows `C:/Users/XXXXX`)
2. Add `//npm.pkg.github.com/:_authToken=TOKEN` to the file and replace `TOKEN` with your personal access token.
  * Find token / create token in Github (Setting-> Developer settings -> Personal access tokens) https://github.com/settings/tokens
  * Under Generate new token select(read:packages   Download packages from GitHub Package Registry)
3. Run `npm install`
4. Run `npm start`
5. Voila!

## How to add new components
When you need to create a new component, you need to figure out where to put it. The following questions can help you decide that:
 
1. If it is a smart component, then it should be added as a new module in the [Xena.WebComponents repository](https://github.com/EG-BRS/Xena.WebComponents).
2. If it is a dumb component then it should be created as a Stenciljs Component in [Xena.DesignSystem repository](https://github.com/EG-BRS/Xena.DesignSystem). Then that component will be usable in both Xena Core UI as well as in Angular components.

### Creating a new Module for use in Xena.WebComponents

Adding a new module to the Xena.WebComponents repository is quite simple. You go to the folder containing the Xena.WebComponents project and type this:

```bash
ng g m my-component-name
``` 

Afterwards you can easily create a new component under that module like this:

```bash
ng g c my-component-name/my-component-name
``` 

### Define the Component to expose as a WebComponent
In your module you can define one (and only one) component to expose as a webcomponent. You do that by defining a conventional property called customElementComponent. 
```
export class MyComponentModule {
  customElementComponent: Type<any> = MyComponent;
}
```

### Setup selector in Xena.WebComponents AppModule
Final step is to add the selector for your component in the main module of Xena.WebComponents. You do that by expanding the lazyConfig in app.module. You can do it like this:
```Javascript
const lazyConfig:: LazyComponentRegistry = {
  definitions: [
    createDef('sign', () => import('./sign/sign.module').then(m => m.SignModule)),
    createDef('my-component', () => import('./my-module/my-module.module').then(m => m.MyModule))
  ],
  ....
}
```
**Remark:** Your selector will always be prefixed with `xwc-` as defined in the lazyConfig.

## Development server

Run `npm start` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.

## Hosting build locally (fx. for test in Xena locally)

Run `npm run host` to build a development release and host it locally on `http://localhost:8081`. 

Change value of `XenaWebComponentsUrl` in `src/Xena.Web/Web.config` to `http://127.0.0.1:8081/{lang}/xena-webcomponents.js`
```XML
<add key="XenaWebComponentsUrl" value="http://127.0.0.1:8081/{lang}/xena-webcomponents.js" />
```
**Remark:** Don't commit these changes

## Running unit tests

Run `ng test` to execute the unit tests. 


### Watch test

Run `ng test --watch` to watch tests. Will run when files change.
se teset on web `http://localhost:9876/`

### Code coverage
Run `ng test --code-coverage` to run tests with coverage. This will also generate the Code Coverage report `coverage/index.html`.
`(your path)` `~/Xena.WebComponents/coverage/webstall/index.html`

### More options
See advanced options here: https://angular.io/cli/test


## Deploying new version to Xena

1. Create a new release of *Xena.WebComponents* by merging into *master* branch.
2. In the [Xena repository](https://github.com/EG-BRS/Xena) update the value of `XenaWebComponentsUrl` in `src/Xena.Web/Web.config` to point to the newest version like:
```XML
<add key="XenaWebComponentsUrl" value="https://cdn.jsdelivr.net/npm/@xenabiz/xena-webcomponents@1.0.18/dist/prod/{lang}/xena-webcomponents.js" />
```

## Online Demo

[Demo](https://components-dev.xena.biz/) 

## Known issues

### Running translations gives error

> This solution has been added to i18n script! So you wont need to manually run it!

Running `npm run i18n` will result in `Error: error:0308010C:digital envelope routines::unsupported` error

This is due to our old Angular version and the new Node version (nodejs v17+) isn't compatible.

Fix this by going to Visual Studio Code open a terminal run `export NODE_OPTIONS=--openssl-legacy-provider`