fquffio / zanichelli-design-system

Design system Zanichelli

Zanichelli - Web Components Library

Zanichelli's design system is widely documented on Zeroheight at this link.

Install

yarn add @zanichelli/albe-web-components

Start Library Development Server

yarn start

---

Create a component:

yarn generate component my-component

NB: component name must have a dash (-)

---

Symlink Local Development

Run

yarn link

In the destination project folder run

yarn link @zanichelli/albe-web-components

---

Tests

Run all tests

yarn test

Run single test

yarn test --spec {componentPath}

Run e2e tests

yarn test.e2e

---

Release

In this repository we follow the Conventional Commits Specification and we use standard-version to update the CHANGELOG.md when publishing a new version of the package to NPM.

Standard-version automatically detects the type of the update (patch, minor or major) following the Semantic Versioning specification.

Publish a new version on NPM registry

• Make sure you are logged in NPM
• Run standard-version:

yarn release

Specify a version

If you want to select a version or the update type, you can use the --release-as flag:

yarn release --release-as path
yarn release --release-as 1.1.0

In general, you can pass any flag supported by standard-version, please refer to their CLI usage documentation.

Publish the new release on GitHub

You need to manually create the GitHub release in order to update the Storybook documentation.

---

Documentation

In order to correctly import Stencil Components into the Storybook, we need to build the library first. Stencil will generate properties documentation and it will store them in the custom-elements.json which is loaded by Storybook. At the moment, everytime you edit the library sources, you need to rebuild them to get the Storybook updated.

Plugins

• @storybook/addon-a11y
• @storybook/addon-docs
• @storybook/addon-knobs
• @storybook/addon-viewport
• storybook-addons-abstract

Start Storybook:

# Build the library
yarn build
# Start the Storybook
yarn start-storybook

Build Storybook:

# Build the library
yarn build
# Build the Storybook
yarn build-storybook

Developing with Storybook:

Start the Stencil dev server:

yarn start

and, in a separate terminal window, run the Storybook:

yarn start-storybook

---

Build Library package

yarn build

Environment Support

• Modern browsers
• Chromium Edge and Safari 10 with polyfills

Edge	Firefox	Chrome	Safari
> 16.16	> 48	> 69	> 10.0

Usage

CSS Custom Properties

The library provides a global css variables export. You can import the styles by ES6 import:

import '@zanichelli/albe-web-components/www/build/web-components-library.css';

or via link tag:

<link type="text/css" rel="stylesheet" href="https://unpkg.com/@zanichelli/albe-web-components/www/build/web-components-library.css" />

Custom Elements

You can use the library by importing the custom elements from npm package:

import { defineCustomElements, applyPolyfills } from '@zanichelli/albe-web-components/loader';

applyPolyfills().then(() => {
  defineCustomElements(window);
});

or via a script tag:

<script src="https://unpkg.com/@zanichelli/albe-web-components/dist/web-components-library/web-components-library.esm.js"></script> 

Then use the relative tag as a usual component in your markup.

<section>
  <z-button label="button" type="primary">Click me!</z-button>
</section>

Using React bindings

Albe's Web Components come with automatically generated React bindings. This means that you can use Web Components in a React application without the need to wrap component references, with full intellisense support thanks to TypeScript definition files for bindings.

You still need to import and run polyfills, then you can import Component references from the React submodule:

import React from 'react';
import ReactDOM from 'react-dom';
import '@zanichelli/albe-web-components/www/build/web-components-library.css';
import { defineCustomElements, applyPolyfills } from '@zanichelli/albe-web-components/loader';
import { ZButton } from '@zanichelli/albe-web-components/react';

applyPolyfills().then(() => {
  defineCustomElements(window);
});

ReactDOM.render(<ZButton>Click me</ZButton>, document.getElementById('root'));

Component definition

Each component is structured as follows:

File name	Description
index-ts	Component markup and UI logics
styles.css	Component styles
index.spec.ts	Component tests
index.stories.mdx	Component storybook file
README.md	Stencil documentation

Roadmap

• 12 6 2020: Publishing repo v 1.0.0