post-components

v0.0.24

Published

2 years ago

A few bunch of web components built with StencilJS

Downloads

0High
0Medium
0Low

loic57

Post components kit

Introduction

This project is based on two technos:

StencilJS : Stencil is a toolchain for building reusable, scalable Design Systems. Generate small, blazing fast, and 100% standards based Web Components that run in every browser.
Storybook : Storybook is an open source tool for building UI components and pages in isolation. It streamlines UI development, testing, and documentation. In our case Storybook will be used as a documentation system.

How to install

git clone ''
cd employee-design
npm install

How to launch the project

You'll need two terminals :

npm run build-stencil:watch : For building and watching web components in Stencil.
npm run start-storybook: For displaying our web components in a beautiful documentation.

Structure

To make it easier, only the main folders/files are displayed below.

.storybook/main.js: The main configuration file. This file controls the Storybook server's behavior, so you must restart Storybook’s process when you change it. (Based on webpack 4)
.storybook/preview.js: This is loaded in the Canvas tab in Storybook, the “preview” iframe that renders your components in isolation. Use preview.js for global code (such as CSS imports or JavaScript mocks) that applies to all stories. More info
dist and loader: These 2 folders contains all components in vanilla javascript (to be understood by any type of framework) with their polyfills. These 2 folders are the base if you need to create a NPM package.
public: Contains assets (images, icons, fonts, ...) for Storybook
src: This folder hosts all the stencil components in typescript + the differents stories
src/assets: assets for Stencil
src/components: Stencil components
src/components: CSS and SCSS for Stencil components
introduction.stories.mdx: Homepage

What is a web component?

A Web component or "Custom Tag Element" is a reusable piece of code built in vanilla JS. A web component needs 3 things to work (one of them is optional)

Custom Tag: By default, you use standard HTML tags as <header>, <div>, <span>, <body>, ...These tags are built by the browser. A custom tag is exactly as a standard HTML except that It is created by a developer. This custom tag will wrap all the template + logic + style of the component. Example: <post-button> is a valid custom tag. But <postButton> is not. A custom tag needs to be composed of two words linked by a dash.

HTML Template: The custom tag that you'll use will not work alone. It needs to load an HTML template. It's simply the markup of the component. Example:

<post-card>

will render

<div class="post-card">
    <div class="post-card__image">...</div>
    <div class="post-card__content">
        <div class="post-card__heading">...</div>
        <div class="post-card__text">...</div>
        <a href="#" class="post-card__link">...</a>
    </div>
</div>

Shadow DOM (optional): A web component can possess a shadow DOM. It's like a DOM but only for your web component. In this way you reduce the possibilities of having CSS conflicts and other benefits like HTML class naming convention.

React library integration

More details (https://stenciljs.com/docs/react)

Add new react component library from template

Add a new react component library (ex: component-library-react) in an another repository (parent folder for instance)

git clone https://github.com/ionic-team/stencil-ds-react-template component-library-react
cd component-library-react
npm i

Change proxies file to target your new library package created previousely

In stencil.config.ts (in employee-design folder)

import { Config } from '@stencil/core';
import { reactOutputTarget as react } from '@stencil/react-output-target';

export const config: Config = {
    ...
    outputTargets: [
        reactOutputTarget({
          componentCorePackage: 'stencil-storybook',
          proxiesFile: '{path to created package library}/src/components/stencil-generated/index.ts',
          includeDefineCustomElements: true
        }),
        {
        type: 'dist',
        esmLoaderPath: '../loader',
        },
        {
        type: 'dist-custom-elements',
        },
        ...
    ],
};

Build react library

Build stencil project (in employee-design folder)

npm run build

Install stencil dependency

Go to the react component library (ex: component-library-react) then run

cd {path_to_react_component_library}
npm install {path_to_stencil}

ex:

cd component-library-react
npm install ../employee-design

Install React components library to you react project

Go to your react project and install the react component library

cd {path_to_react_project}
npm install {path_to_react_component_library}

cd employee
npm install ../component-library-react