|
1 | | -[](https://stenciljs.com) |
| 1 | +# Including the CBP Design System Web Components |
2 | 2 |
|
3 | | -# Stencil Component Starter |
| 3 | +There are a couple strategies for including the CBP Design System web components in your site or application, detailed below. |
4 | 4 |
|
5 | | -This is a starter project for building a standalone Web Component using Stencil. |
| 5 | +## Node Modules |
6 | 6 |
|
7 | | -Stencil is also great for building entire apps. For that, use the [stencil-app-starter](https://github.com/ionic-team/stencil-app-starter) instead. |
| 7 | +The CBP Design System [web components](https://www.npmjs.com/package/@cbpds/web-components) (and [React wrappers](https://www.npmjs.com/package/@cbpds/react-components)) are published to npm. |
8 | 8 |
|
9 | | -# Stencil |
| 9 | +In modern JavaScript frameworks, you can use the native web components, which are framework-agnostic. To add the CBP Design System web components to your project, do the following: |
10 | 10 |
|
11 | | -Stencil is a compiler for building fast web apps using Web Components. |
| 11 | +- Run `npm install @cbpds/web-components --save-dev` |
| 12 | +- Import the web components loader in your framework's top-level file such as `App.js|jsx|tsx` or `main.js|jsx|tsx`. |
| 13 | +- Call `defineCustomElements()` to initialize the loader and register the web components (to be lazy loaded when used). |
12 | 14 |
|
13 | | -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. |
14 | | - |
15 | | -Stencil components are just Web Components, so they work in any major framework or with no framework at all. |
| 15 | +``` |
| 16 | +import { defineCustomElements } from '@cbpds/web-components/dist/esm/loader.js'; |
16 | 17 |
|
17 | | -## Getting Started |
| 18 | +defineCustomElements(); |
| 19 | +``` |
18 | 20 |
|
19 | | -To start building a new web component using Stencil, clone this repo to a new directory: |
| 21 | +## Script tag |
20 | 22 |
|
21 | | -```bash |
22 | | -git clone https://github.com/ionic-team/stencil-component-starter.git my-component |
23 | | -cd my-component |
24 | | -git remote rm origin |
25 | | -``` |
| 23 | +For sites not running in a node.js environment or requiring a build step, the web components may be included via script tag: |
26 | 24 |
|
27 | | -and run: |
| 25 | +- Put a script tag referencing the loader module in the head of your index.html or template file. |
| 26 | + - This file is a loader, which registers all of the design system components and lazy-loads individual components as needed. |
| 27 | + - Note: ESM modules must be delivered over SSL/https. |
| 28 | + - Then you can use the web components (custom elements) anywhere in your template, JSX, html, etc. |
28 | 29 |
|
29 | | -```bash |
30 | | -npm install |
31 | | -npm start |
32 | | -``` |
| 30 | +You can use UNPKG (an open source global content delivery network that mirrors npm) for testing, but it should never be used for production apps. |
33 | 31 |
|
34 | | -To build the component for production, run: |
| 32 | +Referencing the latest version: |
35 | 33 |
|
36 | | -```bash |
37 | | -npm run build |
| 34 | +``` |
| 35 | +<script type="module" src="https://unpkg.com/@cbpds/web-components/dist/cbp-web-components/cbp-web-components.esm.js"></script> |
38 | 36 | ``` |
39 | 37 |
|
40 | | -To run the unit tests for the components, run: |
| 38 | +Referencing a specific version: |
41 | 39 |
|
42 | | -```bash |
43 | | -npm test |
| 40 | +``` |
| 41 | +<script type="module" src="https://unpkg.com/@cbpds/[email protected]/dist/cbp-web-components/cbp-web-components.esm.js"></script> |
44 | 42 | ``` |
45 | 43 |
|
46 | | -Need help? Check out our docs [here](https://stenciljs.com/docs/my-first-component). |
| 44 | +Ideally, your application should reference an central, organization-hosted copy of the files or pull the package's `dist/cbp-web-components` directory into your application's "assets" directory and reference them as such: |
47 | 45 |
|
| 46 | +``` |
| 47 | +<script type="module" src="./assets/cbp-web-components/cbp-web-components.esm.js"></script> |
| 48 | +``` |
48 | 49 |
|
49 | | -## Naming Components |
| 50 | +# Using the CBP Design System Web Components |
50 | 51 |
|
51 | | -When creating new component tags, we recommend _not_ using `stencil` in the component name (ex: `<stencil-datepicker>`). This is because the generated component has little to nothing to do with Stencil; it's just a web component! |
| 52 | +Once the CBP Design System web components have been included in your site or application, the are used like any other HTML elements - they are custom elements, after all. |
52 | 53 |
|
53 | | -Instead, use a prefix that fits your company or any name for a group of related components. For example, all of the Ionic generated web components use the prefix `ion`. |
| 54 | +It is recommended that the [`cbp-app` web component](https://us-cbp.github.io/design-system/?path=/docs/components-app-specifications--docs) is used to wrap the entire contents of your application or site template to include the global CSS variables (design tokens) that are used throughout the design system for styling the components. |
54 | 55 |
|
| 56 | +To get started quickly, you may copy the markup from one of our ["template" stories](https://us-cbp.github.io/design-system/?path=/story/patterns-page-templates--internal) to wrap your application or site content. |
55 | 57 |
|
56 | | -## Using this component |
| 58 | +# Fonts and Assets |
57 | 59 |
|
58 | | -There are three strategies we recommend for using web components built with Stencil. |
| 60 | +Regardless of how you include the web components (either method above), you'll still need some assets that are part of the CBP Design System package but are not encapsulated in the `cbp-app` web component or any others: |
59 | 61 |
|
60 | | -The first step for all three of these strategies is to [publish to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages). |
| 62 | +Copy the files in `node_modules/@cbpds/web-components/dist/assets/` to your application /assets directory. (This may be automated with a "copy" command in your application). This directory includes the Roboto font files, their CSS font face definitions, and the CBP Seal, which is used in multiple places and may be referenced as a favicon. |
61 | 63 |
|
62 | | -### Script tag |
| 64 | +The Roboto font family is part of the CBP Design System standards, but must be linked manually in your application's `<head>` as well. |
63 | 65 |
|
64 | | -- Put a script tag similar to this `<script type='module' src='https://unpkg.com/[email protected]/dist/my-component.esm.js'></script>` in the head of your index.html |
65 | | -- Then you can use the element anywhere in your template, JSX, html etc |
| 66 | +Copy and paste the following into your index.html or template file: |
66 | 67 |
|
67 | | -### Node Modules |
68 | | -- Run `npm install my-component --save` |
69 | | -- Put a script tag similar to this `<script type='module' src='node_modules/my-component/dist/my-component.esm.js'></script>` in the head of your index.html |
70 | | -- Then you can use the element anywhere in your template, JSX, html etc |
| 68 | +``` |
| 69 | +<link rel="icon" type="image/svg+xml" href="assets/images/cbp-seal.svg"> |
| 70 | +<link rel="stylesheet" type="text/css" href="./assets/css/roboto.css"> |
| 71 | +<link rel="stylesheet" type="text/css" href="./assets/css/roboto_mono.css"> |
| 72 | +``` |
71 | 73 |
|
72 | | -### In a stencil-starter app |
73 | | -- Run `npm install my-component --save` |
74 | | -- Add an import to the npm packages `import my-component;` |
75 | | -- Then you can use the element anywhere in your template, JSX, html etc |
| 74 | +If the path to your application's assets folder is different than `"./assets"`, you may need to provide the paths as properties of the `cbp-universal-header` component as part of your site/application template. |
0 commit comments