blox

Library of web components implementing Pixlee TurnTo design system.

This project uses LitElement to build web components. Follow the guides for more info on how to write components.

Get started

See:

• Example of web component in src/components/blox-sample/blox-sample.ts
• How it's used in dev/index.html
• Unit tests in src/components/blox-sample.test.ts

Install

1. Clone this repo
2. Run

# Retrieves the auth token for fontawesome-pro
FA_AUTH_TOKEN=`vault kv get -field=value secret/production/fa_auth_token`

npm install

If vault kv get fails, you might need to login:

vault login -method=github token=$VAULT_GITHUB_TOKEN

If $VAULT_GITHUB_TOKEN is empty in your environment, refer to https://pixlee-wiki.atlassian.net/wiki/spaces/PD/pages/704839684/Developer+Environments+Setup#Environment-Variables.

Build

npm run build

Build files are located in ./build:

• index.js is a bundle containing all the components
• dist/components/* are individual bundles for each component

Dev

npm start

Will start a dev server in watch mode. Go to http://localhost:8080. Any change in the source will trigger a rebuild/reload.

Dev with Storybook

It is also possible to use Storybook in dev mode. Run

npm run storybook

It will start storybook in dev mode at:

http://localhost:6006/

Any change you make to the source will trigger a page refresh in storybook, with the changes

Test

npm run test

See test example in src/components/blox-sample.test.ts. Some more resources about testing:

• https://dev.to/open-wc/testing-workflow-for-web-components-g73
• https://open-wc.org/guides/knowledge/testing

Tests are run by Web test runner which run the tests in a headless browser (preferred for web components)

Coverage data is created in coverage/. Open coverage/lcov-report/index.html.

How to add a new component

1. Create a folder under ./src/components (for example ./src/components/my-new-component)

2. Create a .ts file for the component: ./src/components/my-new-component/my-new-component.ts

3. Add component code. Here is a sample to get started:

   import { LitElement, html, customElement } from 'lit-element';
   
   @customElement('my-new-component')
   export class MyNewComponent extends LitElement {
       render() {
           return html`
               <div>Hello from my-new-component!</div>
           `;
       }
   }
   

4. In dev mode, use you component in /dev/index.html. For example add <my-new-component></my-new-component>

Consume/Use web components from this lib

1. Add the build script to your page

   • Either consume the entire lib

         <script type="module" src="./build/dist/blox-all.js" />
     

   • Or consume components one by one

         <link rel="stylesheet" href="./build/dist/blox-styles.css" />
         <script type="module" src="./build/dist/components/blox-sample/blox-sample.js" />
     

   NOTE: Don't forget type="module" !. NOTE: Including blox-styles.css is only required when consuming individual components. Otherwise, it's included in blox-all.js.

2. Use the components in your HTML! <my-new-component></my-new-component>.

   NOTE: Custom elements cannot be self-closing because HTML only allows a few elements to be self-closing. Always write a closing tag (<my-new-component></my-new-component>).

Storybook

Local

Start storybook:

npm run storybook

Go to http://localhost:6006/

Deployed

On each push, changes are deployed to storybook hosted on chromatic at (github login required):

https://www.chromatic.com/library?appId=608b33c3b504fb0021f00570

The deployment is made through github actions, configuration in .github/workflows.

Chromatic has features like visual regression testing and design review. 3 minutes intro to chromatic: https://www.youtube.com/watch?v=9o6uB1X-LZ8

Writing stories

See example story in src/blox-sample/blox-sample.stories.ts. Each exported member will be a story.

Storybook Controls can be used in a story to modify properties live. See Default story in src/blox-sample/blox-sample.stories.ts for an example. When starting story, we automatically run web-component-analyzer to analyze our components and extract properties. This generates custom-elements.json which is passed to storybook (see in .storybook/preview.js), which uses that to generate the appropriate controls.

Goodies

• Checkout this VSCode extension for Syntax highlighting, type checking and code completion for lit-html, and other things!