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

Linting and autofixing of the code style

There are some tools installed to help keeping uniformity of code style:

• Eslint
• Stylelint
• Prettier

Install the related official extensions in your IDE to get live errors and warning while coding.

Run lint checks and auto-fix

Prettier check

yarn prettier-check

Prettier auto-format

yarn prettify

TypeScript lint check

yarn lint.eslint

CSS lint check

yarn lint.stylelint

TypeScript auto-fix

yarn lint-fix.eslint

CSS auto-fix

yarn lint-fix.stylelint

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
• Make sure you built the components with yarn build
• 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 minor
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.

Plugins

• storybook-addon-stencil - custom Storybook plugin for Stencil
• @storybook/addon-controls
• @storybook/addon-docs
• @storybook/addon-viewport

Start Storybook:

# Start Storybook
yarn start-storybook

local development with Storybook comes with live reloading.

Build Storybook:

# Build the library
yarn build
# Build Storybook
yarn build-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:

// using jsDelivr
<link
  type="text/css"
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@zanichelli/albe-web-components/www/build/web-components-library.css"
/>

// using unpkg
<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} from "@zanichelli/albe-web-components/loader";

defineCustomElements(window);

or via a script tag:

// using jsDelivr
<script src="https://cdn.jsdelivr.net/npm/@zanichelli/albe-web-components/dist/web-components-library/web-components-library.esm.js"></script>

// using unpkg
<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 variant="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.

Import components reference 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} from "@zanichelli/albe-web-components/loader";
import {ZButton} from "@zanichelli/albe-web-components/react";

defineCustomElements(window);

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

Component definition

Each component is structured as follows:

| File name | Description | | ------------------ | ---------------------------- | | index.tsx | Markup and UI logics | | styles.css | Styles | | index.spec.ts | Tests | | index.mdx | Storybook's markdown | | index.stories.ts | Storybook's CSF stories | | readme.md | Auto-generated documentation |