@unifyux/web-components v0.0.28

PerkinElmer Web Component Library

Storybook (live demo & documentation)

Web Components Storybook

React Components Storybook

Goals

Primarily the goal is to support the implementation of the PerkinElmer design system, by providing a set of reusable components that:

• Have the desired look and feel
• Have minimal external dependencies
• Can be used as drop-in replacements for HTML elements
• Follow accessibility best-practices
• Are compatible with multiple application frameworks, eg. Angular, React
• Are well tested and robust
• Are supported by the required browsers
• Are well documented
• Are easy to install and use
• Are internationalized: contain translations of internal strings, for supported languages (TBD)
• Should be internalionalized: format values and display names according to locale
• Should work in RTL locales
• Provide a way to insert custom strings to override default strings used

Technology

Web Components (v1)

To be widely compatible and almost as easy as using built-in HTML elements, the components are Web Components, ie. they are made with the following new web standards:

• Web Components
• Custom Elements
• Shadow DOM
• HTML Template Element
• Custom Events

Note: the Web Components specification was initially proposed by Google, but it was not standardised as originally proposed. For example HTML Imports have not been made part of the official spec. The official specification is referred to as v1, the initial version as v0. Be careful when browsing the web, that any resources are referring to the new official spec.

Stencil (Web Component toolkit)

Stencil allows writing, testing, documenting, and publishing web components easily. It provides a component API over the native one, making it simpler to create components, without handling many low level details of the specification. Components are written in Typescript, using JSX to generate markup, similarly to React. It is well documented, and has also been adopted by some major companies to produce their design systems.

Stencil provides a dev-server which live-reloads changes, which can by run with this command:

yarn start

Browser Support

• Chrome, Safari, Firefox, Edge
• IE 11 (with polyfills)

Static Documentation

This is provided by README markdown files in the github repository, which Github renders as HTML. Stencil generates API documentation for the components in these files as well.

Interactive Documentation (Storybook)

To run Storybook locally,

yarn run storybook

will start a local server and open a browser window with the Storybook UI. This will allow interacting with the components in various states, and also viewing the generated documentation in the Notes panel.

Theming

The components are themed by the use of CSS custom-properties. By changing the values of these, the appearance of the components can be customized. We will use this to create the desired look and feel, as that evolves from the Design System team's research.

Custom Themes

The themes are defined in the web-components/src/themes directory, as subdirectories. Each theme directory contains theme.css file which exports a list of CSS properties which the components consume in their own CSS files.

Currently, the only theme is the 'clinical' theme, and the 'default' one is simply a copy of that, in order to keep the names of properties in sync. Creating a new theme involves copying the 'default' theme directory and renaming it. Then the properties in the theme.css can be changed to customize the theme.

Warning: once you create a new theme, it must be maintained in order to keep the properties up to date with any changes in the 'default' theme. Some kind of script to validate the themes should be written at some point :).

Figma integration

Building

yarn run build

Will transpile source code and generate distributable modules in dist/ directory. This also regenerates documentation in docs directory.

Unit Tests

Are written using Jest. To run unit tests:

yarn run test

To run units tests, and rerun after code changes:

yarn run test:watch

Usage / Importing into your Project

Basic HTML Integration

Add the JavaScript and CSS resources to your in index.html or equivalent file:

<link rel="stylesheet" href="https://unpkg.com/@unifyux/web-components@0.0.17/dist/web-components/themes/clinical/theme.css" type="text/css" media="screen" />

<script type="module" src="https://unpkg.com/@unifyux/web-components@0.0.17/dist/web-components/web-components.esm.js"></script>
<script nomodule src="https://unpkg.com/@unifyux/web-components@0.0.17/dist/web-components/web-components.js"></script>

There are 2 .js files: the first is used by modern browsers, the second by IE, and other legacy browsers.

To use a different version, change the version identifier after the @ character in the above URLs. To see which versions are available, visit the public NPM page for this package. Click on the Versions tab to see the available versions.

Once you've loaded the web components in your app, you can simply use them as HTML elements... eg.

<pki-link href="http://google.com">Google</pki-link>

Will create a regular link, but styled according to the design system.

To see which components are available, have a look at Storybook (see above), which also has documentation for each component in the Notes tab, which will tell you what properties the component accepts. Note that the storybook does not have hot-reloading enabled, so you'll need to do a yarn build to rebuild the components and reload the storybook manually to see changes. Use yarn storybook to run the storybook locally.

React Components

Are automatically generated in the sibling package react-components. You can import and use these like any other 3rd party React component. Eg.

import { Nav, NavItem } from '@unifyux/react-components';

To set the theme in a React app, import the theme css in your main component:

import '@unifyux/web-components/dist/web-components/web-components.css';

Angular 9+ Components

Are similarly generated in the angular-components package. If you're using AngularJS, you will have to use the vanilla HTML integration route.

Development Workflow

For interactive development, use the yarn start command to start the Stencil server, running the index.html page in the src/ directory. It will update automatically when you edit the source files. If that does not work properly, you may need to restart the server. This seems to happen when a new CSS variable is added, for example.

Every time you push to a feature branch, or develop, a new 'canary' version will automatically be published to NPM (this applies to all packages in the Unify monorepo). To release a proper version, you'll need to use the top level 'release' script to bump the version number, and that will be published to NPM when it is merged to master. This is useful for testing integration in another application.

Local CDN Server

Since it is still annoying to have to publish to NPM to debug changes in your app, there is a simpler way, which is to host the entire monorepo on a local webserver. For convenience, you can use the yarn dev-server script in the top level of the repository. Then, instead of linking to NPM as described above, you just link to the assets you need in the dist/ directory of the package. Eg.

<link rel="stylesheet" href="http://localhost:8082/packages/web-components/dist/web-components/web-components.css" />
<script type="module" src="http://localhost:8082/packages/web-components/dist/web-components/web-components.esm.js"></script>
<script nomodule src="http://localhost:8082/packages/web-components/dist/web-components/web-components.js"></script>

Will load the web-components from your local package. You will need to do a yarn build to reflect your latest changes since the server started.

Using Local React / Angular components

This is possible by using yarn link in the web-components, react-components, or angular-components package directories.

Then in your app repo, use yarn link @unifyux/web-components to use the local version.

Resources

• Stencil Tricks
• Testing Stencil
• Cross Browser Testing
• Open WC browser testing guide
• Karma testing web components
• Input validation with Stencil