Genesys Web Components

This repo contains a set of custom elements that can be used across Genesys' UIs to provide a common user experience.

Updates

If you are a consumer of this library, please subscribe to the "Common UI Development" mailing list to recieve any important updates about breaking changes or upcoming releases. You can find instructions on how to subscribe to a new mailing list here, under "Self-Service Email Distribution Groups"

You may also want to join the chat room for the Genesys Cloud Common UI Development Group

At any given time there are three types of components present in the library:

• stable: Most components fall into this category, and there will be no breaking api changes outside of a major release.
• beta: New components where the API design is still being explored. Breaking changes may happen without a major version change.
• legacy: Old components that have been replaced by a new component, or a newer version of the component witn an incompatible API. These will be removed in the next major release.

For more details on the component evolutin process see the full documentation on the topic

Demo/Documentation

Lives here

Installing the library

Prerequisites

Published artifacts are stored in our private artifactory/jfrog registry, so you will need to update your .npmrc file to use artifactory. There are some basic instructions availabe for this. This registry proxies the main NPM registry, but if you need to also use other private registries some manual editing of your configuration may be necessary. Please read up on the npmrc docs or ask around in one of the Genesys Cloud UI chat rooms if you need help with that.

Install

npm install -E @genesys/common-webcomponents@alpha

or

yarn add -E @genesys/common-webcomponents@alpha

The -E is for exact-version while we are in alpha and breaking changes may still be possible, so you will need to manually upgrade when needed.

Setting up your App

Stylesheets

The library provides a baseline set of CSS styles in the package under dist/genesys-webcomponents/genesys-webcomponents.css. The stylesheet provides:

• Baseline styles for browser elements
• Classes for specific typography patterns
• CSS variables for colors
• CSS variables for spacing (coming soon)

The best mechanism for importing the stylesheet into your project will depend on how you handle CSS in your project in general. Reach out to the Common UI Development group if you're having trouble with your specific integration.

Genesys Cloud applications

Genesys Cloud applications, or other always-online apps should import the library and call registerElements early during application bootstrap to register the components with the browser.

import { registerElements } from '@genesys/common-webcomponents';
registerElements();

This will register the custom elements and automatically configure stencil to load icons and internationalization files from our CDN. You shouldn't need to bundle any additional assets into your application.

Premise/Hybrid applications

If your application runs on local networks and needs to work when the general internet is inaccessible, you'll want to directly use stencil's loader.

import { defineCustomElements } from '@genesys/common-webcomponents/loader';
defineCustomElements();
// for optional lazy-loaded custom resource location:
// defineCustomElements(window, { resourcesUrl: 'path/to/deployed/resources' });

You'll also need to make sure the contents of @genesys/common-webcomponents/dist/genesys-webcomponents/ are deployed with your application so that stencil's lazy-loading can fetch those resources. See the stencil integration docs for more details.

IE 11 support

Since IE11 does not support web components natively, you will need to apply polyfills in order to support it.

Component-specific polyfills

component	web api that requires polyfill
gux-tabs	ResizeObserver

Localization

You will need to set a lang attribute on the Gux component or one of its ancestor elements and the Gux component will use that to decide what language to use. For example you could set it on the page somewhere at a high level, e.g. <html lang="en"> or <body lang="en"> and all the Gux components will use that to decide what language to use.

Development and Contribution

The common component library has a very small set of developers, who also work on other projects, so contribution from users is welcome. If you need a new feature, the best way to get it is to work with the team to implement it yourself. You can see the current backlog of tickets in the COMUI JIRA project.

Prerequisites

• THIS IS THE MOST IMPORTANT PART: Read the Contributing Guidelines before starting development work.
• Request access to GenesysCloud Resources including Bitbucket
• Join the chat room for the Genesys Cloud Common UI Development Group and let us know what you're working on!

Serving component and docs

Once you've checked out the project, this is the easist way to see your component as you work on it.

npm run dev

then navigate to http://localhost:8080/ to see the docs

If you want the docs to be accessible externally you can use

npm run dev.public

this will host the docs on http://0.0.0.0:8080/. This means they are available elsewhere on your network at http:/<your-ip-address>:8080/.

Running tests

npm run test

or

npm run test.watch

Documenting your component

To document a component, add an entry under docs/src/components-spec.json describing any attributes and events for your component, and place an example.html file in the component directory the demonstrates the use of the component. Afterward, it will show up in the documentation site.

Localizing your component

Documentation about localizing components can be found in the wiki