@zanichelli/albe-web-components

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 commit-and-tag-version to update the CHANGELOG.md when publishing a new version of the package to NPM.

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

Publish a release using GitHub actions

• Access GitHub and log in as an authorized user
• Go to the repository in the section New release version
• Click on Run workflow (on the right in the blue box)
• To release a latest version: choose master as the branch and select the version type (patch, minor, major) from the dropdown, then click on the Run workflow button.
• To release a release candidate version specify the branch, the version tag and the version name, then click the button. In this case, the branch needs to be different from master, otherwise the action will publish a latest version anyway, ignoring version and tag names.

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