@six-group/ui-library v4.3.2

Six UI Components

This is the actual UI components library.

The Webcomponents in this library are built with Stencil.

Stencil

Stencil is a compiler for building fast web apps using Web Components.

Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec.

Stencil components are just Web Components, so they work in any major framework or with no framework at all.

Getting Started

To start building a new webcomponent using Stencil:

npm run generate six-name-of-new-component

This will create a new folder containing everything necessary for you to develop a new component

To run the unit tests for the components, run:

npm test

Need help? Check out our docs here.

Testing

To run all unit and e2e tests simply execute

npm run teste2e

If you want to run a specific file, simply add the filename ad the end to the command above:

npm run test:2e components/six-button/test/six-button.e2e.ts

For debugging stencil provides the --devtools flag. This will slow down chrome and open the devtools automatically.

Simply add a debugger; statement in the code where you want the test to stop and run:

npm run test:debug components/six-button/test/six-button.e2e.ts

If you need evaluation at a certain breakpoint the easiest is to open the ui-library folder in vscode. The provided launch.json automatically adds the correct runconfigurations to debug tests in vscode

If you want to do some more advanced debugging you can also use page.evaluate. Add the following in your code:

await page.evaluate(() => {
  console.log('this is some evaluation');
  debugger;
});

and run the same command as above:

npm run test:debug components/six-button/test/six-button.e2e.ts

FYI: There seems to be some weird bug when using page.evaluate where the browser first stops in a ghost breakpoint and you have to reload the browser (Ctrl + R) to get to your evaluation endpoint.

Visual Diff Testing

The flag --screenshot allows to run visual diff e2e tests. When we run these tests we will make a screenshot of the component and compare it with previous screenshots. You can find the screenshots in this image folder.

When a screenshot test fails you can open the compare.html which will present you what changed.

When you actually redesigned the component and expect the changes simply delete the old images.

The screenshot tests are not run in the build because the tests seem to always fail in the build and it's very hard to figure out what exactly differs there. So if you want to validate the components are still working properly run it locally:

npm run test:inclScrnsht

Adding documentation

To see the documentation for your component you need to do the following:

• add an index.html to your component folder
• the index.html should have the following structure, where a div with the container class surrounds all your examples. And the code examples are wrapped in <div class="container"></div>: `html

• additionally you need to have an EXAMPLES comment in your readme.md:

  <!-- EXAMPLES -->
  
  <!-- Auto Generated Below -->

Prepare

Before creating a new version make sure that:

• you built the projects to be publish (dist folder should be updated)
• you updated CHANGELOG.md
• you know which version to update to
  • our library follows Semantic Versioning so follow this guide to decide what kind of version update you will bring:
    • MAJOR version when you make incompatible API changes
      • => Users of the SIX Web Components Library must adapt their code to use the new version.
    • MINOR version when you add functionality in a backwards compatible manner, and
      • => Users of the SIX Web Component Library can use new features but must not adapt their existing code.
    • PATCH version when you make backwards compatible bug fixes.
      • => Users of the SIX Web Component Library get a bug fixed but must not adapt their existing code.

There are different ways how to create a new version:

• manually increase the version in the package.json and package-lock.json
• use npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]
  • see here for more details
• use lerna publish

No matter what kind of method you use to bump the version make sure that the different packages are in sync - always publish these together:

• ui-library

• ui-library-react
• ui-library-vue