amber-components

Web Components implementation of the Amber Design System.

This repository is aimed mainly to developers and contributors, for the proper documentation & styleguide please refer to https://amber.bitrock.it.

You can preview/try the components on the live Storybook.

Usage

Install

$ yarn add @amber-ds/components
--- or ---
$ npm install @amber-ds/components

optionally, you may want to add the Web Components polyfills to support previous versions of Firefox and Edge.

$ yarn add @webcomponents/webcomponentsjs
--- or ---
$ npm install @webcomponents/webcomponentsjs

Add in project

You can import the components in your project in different way depending on the environment:

as Javascript files with a bundler (like Webpack)

// myfile.js

// import the whole components library
import AmberComponents from '@amber-ds/components';

// import a single component (button for instance)
import '@amber-ds/components/button',

as Javascript files from HTML without a bundler

<!-- mypage.html -->

<!-- import the whole components library -->
<script type="module" src="./node_modules/@amber-ds/components/index.js"></script>
<!-- import a single component (button for instance) -->
<script type="module" src="./node_modules/@amber-ds/components/button.js"></script>

then in an .html file, or a templating that produces an HTML output:

<!-- myfile.html -->

<amber-button priority="primary">
  Get ready!
<amber-button>

Development

A brief description of the development architecture, stack and how to work on the code:

WebComponents

The WebComponents specification is an umbrella term to group the Custom Elements v1 and Shadow DOM v1 specification. These browser APIs let you write W3C compliant custom HTML tags with their own functionalities, scoped styles and markup that works across browsers and frontend frameworks.

Typescript

To achieve a better code resilience, all components are written in TypeScript to take advantage mainly of static type checking and the decorators syntax. It is also used to transpile code to ES-2015.

Based on Lit-HTML & LitElement

Since Web Components as a standard doesn't handle the rendering mechanics and data-binding, we are adopting Lit-HTML and its Web Component class LitElement as a foundation layer for every comoponent within this library.

Internal utilities

• triggerEvent(element, name, ?detail) - a wrapper to create a new custom event and dispatch it with an optional detail object. Bubbling is already turned on.

Add a new component

To quickly create the required (but minimal) boilerplate for a new Amber component, we have included a small CLI utility:

$ yarn create:component [name]
--- or ---
$ npm run create:component [name]

This will create a subfolder within the ./src/components folder with the two required starter files index.ts and style.scss.

You will only need to import the new component inside the ./src/components/library.ts file to chain it in the dev & build processess.

Styling

You can define the styles of each component using SASS, the main index.scss file within the component folder gets processed by the compiler and then is injected in the Shadow DOM.

If you need to share styles, mixins or whatever else between components you should create a separated file and then import it where they are required.

Tests

At the moment only the core libraries (plain .ts files within the src/libs folder) are being tested via Jest.

Available NPM tasks

Start the project in development mode with a live reload Storybook

$ yarn start

Start the project in development mode with a simple HTML page

$ yarn dev

Create a static Storybook build in the ./dist folder

$ yarn build:storybook

Run the unit tests

$ yarn test:unit

Branching policy

This project follows a simple branching policy:

• master contains only stable code, and should not be updated directly
• development where evolutive or experimental code is written
• gh-pages where the distrubutable static Storybook build files are deployed

Do NOT merge directly development into master (it's admin-locked...), always send a PR to have a review.

Publish a new version

Before attempting to publish a new version of the package on NPM, first run through this checklist:

• tests passes (it is required for PRs)
• increment version number in package.json file following semver guidelines
• report the changes on the amber-website docs

If the release include a new component:

• versioning should be incremented by a minor version
• be sure to add a new entry point webpack.config.js, this is required to create the standalone module
• be sure to import the component and add it in the /src/components/library.ts files, this way it will be accessible when user imports the whole library
• add the component tag name it in the /src/elements.ts array, this can help with Vue.js compatibility in some cases

When a new bumped version is pushed to the master branch it will automatically trigger the deploy on NPM (after all automated checks passes) using the bitrock-admin account.

License

Code in this repo and the Amber Design Sytem logo are distributed by the Bitrock UI Engineering team, released under the MIT license.