WEM Web Components

Components that are specific to workforce engagement management (WEM) should live here.

Any common components that exist in the Genesys styleguide should go in the genesys-webcomponents repository instead.

Demo

A live demo of the latest package can be seen here.

TOC

• Development
  • Using this project
  • Dependencies
  • Run Storybook
  • Build
  • Create a new component
  • Documentation
  • Localizing your component
• Deployment
  • JFrog
  • Jenkins
• Testing
  • Running tests
  • Creating new tests

Development

Please read the Contributing Guidelines before starting development work.

Before you start! Make sure that you have installed ESLint on VSCode.

We require Node and npm to run this project. At the time of writing the versions being used are:

Node: v10.15.3
Npm : v6.4.1

Once Npm is installed, run:

npm i -g eslint

Make sure your .npmrc file is set up correctly setting up this project!

Using this project

In order to import these components into other frontend projects you will need to add a devDependency to your package.json

"devDependencies": {
    "@genesys/wem-webcomponents": "x.xx.x",
    ...
}

To use this dependency please use the install command of your package manager.

To test local changes in PCBA, you can do this:

wem-webcomponents> npm run build
wem-webcomponents> npm link
pure-cloud-browser-app> npm link @genesys/wem-webcomponents
pure-cloud-browser-app> grunt local

Dependencies

Before running this project make sure you have pulled the required dependencies by running:

npm install

Run Storybook

To view the list of component stories run the following command:

npm run dev

this will begin a build task along with adding a watcher and serving you the storybook on this url: http://localhost:9002

The watcher will allow you to make changes on the fly without the need to restart the npm task, but you will still need to refresh the browser. You should use this command when developing.

You can test dark theme in storybook using the right hand side knobs menu.

Build

In order to build the dist output folder execute the command:

npm run build

Note: This is done at the start of the npm run dev task.

This task will compile a dist folder for you along with regenerating any readme documentation for the components and the i18n translations

Create a new component

You can get npm to automatically create a new component for you by running:

npm run create-component

• Component - a generic reusable control
• Feature Component - a feature specific control with business logic
• Rich Component - ???

You can also do this manually by creating a folder in either src/components/feature/<componentName> or src/components/global/<componentName> and then creating the required folders / files within it.

Below is an example for the wem-annotations component structure:

src/components/feature/wem-annotations/wem-annotations.tsx
src/components/feature/wem-annotations/wem-annotations.less
src/components/feature/wem-annotations/wem-annotations.i18n.json
src/components/feature/wem-annotations/stories/story.tsx
src/components/feature/wem-annotations/tests/wem-annotations.e2e.ts
src/components/feature/wem-annotations/tests/wem-annotations.spec.ts
src/components/feature/wem-annotations/readme.md

You can create additional sub-folders as required. To capture child components or data types you could organise the directories as follows:

src/components/feature/wem-annotations/data-types/Annotations.ts
src/components/feature/wem-annotations/data-types/AnnotationStatus.ts
src/components/feature/wem-annotations/wem-annotation-item/...

New components will require the translations team to link it to transifex. Once a new component is in master create a ticket similar to this one https://inindca.atlassian.net/browse/LOCAL-7595

How to do the commit

To do the git commits you should use the command npm run commit. And then follow the instructions on the terminal. This helps to identify the version number for releasing this library. And also helps in keeping the changelog for the library.

Documentation

When creating a new component, all of your Prop's, Event's and Listener's should have a doc string above it to explain what it does along with the params. A readme is generated for each component on a npm run build and will contain your docstrings.

Localizing your component

Documentation about localizing components can be found in the wiki

Each component should includeone or more <componentName>.i18n.<langCode>.json file. these files store your translation key / value objects for each component to indicate the supported languages. The default supported language is English and the file should be named <componentName>.i18n.json. To provide additional localizations you need to provoide new files with the correct lang code and values: For example:

wem-annotations.i18n.fr.json
wem-annotations.i18n.de.json
...

To use the new translations include the following lines to your component.tsx::

import annotationResources from './wem-annotations.i18n.json';
...

private i18n: (resourceKey: string, context?: any) => string;
async componentWillLoad() {
    this.i18n = await buildI18nForComponent(this.root, annotationResources);
    ...
}

Then call the i18n method with your json key and pass in any variables through the context paramter as an object. For example:

// inside component
this.i18n('error.http.generic', { code: 'someCode', message: 'someMessage' });

// inside json
"error.http.generic": "code: {code} - message: {message}",

Deployment

JFrog

We upload our versions to the Genesys private JFrog repo. This allows other projects within Genesys to pull down our package and make use of it - without it being made public.

Jenkins

We use Jenkins to throw up our version to JFrog. To make sure you use the latest version inspect the package.json of Master.

Testing

There are two types of tests:

• end to end tests (e2e tests)
• spec tests (unit tests)

Spec tests do not render a DOM and are completely JS to JS relation. We use spec tests to prove the JS functionality of our components. Spec tests are mostly quicker than E2E as they do not require a full instance Puppeteer to be running.

E2e tests render a DOM and can interact with it. This is mainly used to check the rendering of components.

Running tests

To execute all e2e and spec tests for every component run:

npm run test

To just run one type of tests:

For running just spec tests:
npm run test.unit

For running just e2e tests:
npm run test.e2e

To run a single test suite:

npm run test.unit wem-annotations
npm run test.e2e wem-annotations

Creating new tests

The spec tests should use a beforeEach which instantiates the component you are testing. For example:

beforeEach(async () => {
    component = new WemCoachingWizard();
    component.agents = [{ name: 'Agent One', id: '1' }];
    component.coachingService = new MockCoachingService();
    await component.componentWillLoad();
});

Then you can start calling functions and props on the component. For example:

it('does not allow a length greater than 60', () => {
    component.lengthInMinutes = 61;  // lengthInMinutes is a prop on wem-annotaitons
    component.watchLengthHandler();
    expect(component.lengthValid).toBeFalsy();
});

For E2e tests you shouldn't use the default puppeteer page. you should instead use the wemE2EPage which creates the DOM and your component for you:

import { wemE2EPage } from '../../../../utils/E2EWrapper';
...

beforeEach(async () => {
page = await wemE2EPage(`<wem-coaching-wizard></wem-coaching-wizard>`);
    wizard = await page.find('wem-coaching-wizard');
    await page.waitForChanges();
});

The reason for using wemE2EPage and not the default puppeteer page is due to an import of the Genesys WebComponents being required. Instead of this being handle in every test's beforeEach, it is handled in the wemE2EPage instead.