@core-design/components

Core Components

Package Management

This repo leverages Lerna, a tool for managing multiple packages within the same repo.

Lerna takes the place of typical npm and yarn commands. For a full breakdown of lerna commands, see the lerna readme

Generating React components

The stencil config (stencil.config.js) automatically generates React code for the components-react package whenever stencil builds.

From root:

# This will run the `build` script in any package that has it defined in its package.json
lerna run build

If you make changes to these web components be sure to build stencil and commit any changes to packages/components-react/src/generated.

Publishing to NPM

Lerna provides a simple CLI interface for publishing to NPM. See the root readme for more info.

Getting Started

To start developing your Stencil project, run:

From root:

lerna run start

To start developing your Stencil project in Storybook, run:

From root:

lerna run storybook

Component Structure

Stencil components are plain ES6/TypeScript classes with some decorator metadata.

Create new components by creating files with a .tsx extension, such as core-component.tsx, and place them in src/components.

import { Component, Prop, h } from "@stencil/core";

@Component({
  tag: "core-component",
  styleUrl: "core-component.css",
})
export class Component {
  @Prop() first: string;
  @Prop() last: string;

  render() {
    return (
      <div>
        Hello, my name is {this.first} {this.last}
      </div>
    );
  }
}

To use this component, just use it like any other HTML element:

<core-component first="Stencil" last="JS"></core-component>

Naming Components

When creating new component tags, use the core- prefix and kebab-case.

For example: core-button, core-icon, etc. Custom Elements must contain a dashed name so they do not collide with existing html element names.

API

The API for Stencil closely mirrors the API for Custom Elements v1.

Components

Decorator	Description
@Component()	Indicate a class is a Stencil component.
@Prop()	Creates a property that will exist on the element and be data-bound to this component.
@State()	Creates a local state variable that will not be placed on the element.
@Method()	Expose specific methods to be publicly accessible.

High Level Component Example

View high level component example here

Browser Support

Web Components, specifically Custom Elements, are natively supported in Chrome and Safari and are coming to both Edge and Firefox. A dynamic polyfill loader is already included in order to only load the polyfills for the browsers that are missing specific features.

• Chrome (and all Chromium based browsers)
• Safari
• Edge
• Firefox
• IE 11

Polyfills

Stencil includes a subset of the core-js polyfills for old browsers like IE11, fetch and conditionally downloads the Custom Elements v1 only when it's needed for modern browsers (EDGE and old versions of Firefox.)

Internet Explorer 11

View IE11 polyfill details here

In addition, the following set of polyfills are also included:

• Promise
• fetch()
• CSS variables: We implemented our own CSS variables polyfill that integrates into the Stencil runtime.

All browsers

Some modern browsers like Edge do not include native support for Web Components. In that case, we conditionally load the Custom Elements v1 polyfill.

---