MG Components

This project centralize MGDIS standalone Web Components using Stencil.

Stencil

Stencil is a compiler for building fast web apps using Web Components.

Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements v1 spec.

Stencil components are just Web Components, so they work in any major framework or with no framework at all.

Getting Started

To run MG Components, clone this repository, go to your new directory and run:

# This repository uses pnpm as package manager
corepack enable
pnpm i
pnpm start

To build for production, run:

pnpm build

To run tests for the components, run:

pnpm test

# only unit tests
pnpm test:unit

# only e2e tests
pnpm test:e2e

# filter on filename
pnpm test -- mg-icon
pnpm test:unit -- mg-icon

To regenerate snapshot you must add the --updateSnapshot parameter.

For E2E tests you must use WSL or a Linux OS to get the same screenshots as the GitLab CI.

To add a component, run:

pnpm generate component-path

# example for an atom
pnpm generate atoms/mg-icon

# example for a molecule
pnpm generate molecules/mg-message

Naming Components

All of the MGDIS generated web components must use the prefix mg.

Using this library

You will find how to use the library instructions in the Getting Started section.

Style

Naming methodology

MG Components is using BEM (Block, Element, Modifier) methodology with the two dashes style naming scheme.

Declaration organisation

When a selector contains too many declaration it is recommended to organize them by theme : Display, Decoration, Font, Others.

.mg-button {
  // Display
  display: inline-block;
  vertical-align: middle;
  min-height: 3.5rem;
  padding: 0.6rem 1.2rem;
  // Decoration
  background-image: none;
  border-radius: 0.3rem;
  border: 0.1rem solid transparent;
  cursor: pointer;
  // Font
  font-weight: normal;
  text-align: center;
  white-space: nowrap;
  // Others
  touch-action: manipulation;
}

Storybook

The plugin storybook-addon-docs-stencil is used to generate the doc. To be up to date on local it needs a fresh build.

run

pnpm storybook

Notes

To display components in our stories, we use the filterArgs method to only show the necessary arguments in the code example. It takes in the first parameter an object containing the arguments to be used, and in the second parameter, an object containing the component default values.

const Template = (args: any): HTMLElement => (
  <mg-tooltip {...filterArgs(args, { placement: 'bottom' })}>
    <mg-icon icon="info-circle"></mg-icon>
  </mg-tooltip>
);