README
Ad Hoc Component Library
This is a Web Component library with Storybook integration based on https://github.com/DesignByOnyx/stencil-storybook-starter.git
Features
- automatic generation of stories for all components
- automatic knobs generation for all
@Props
on your components- ability to customize which knobs are used for each prop (though the code does a good job of guessing for strings, numbers, booleans, objects, dates, and colors).
- ability to define multiple states which are rendered on a single page, each with a title, description, and props to use for rendering. A copyable code snippet is also generated for each state (kind of a lightweight chapters implementation)
- ability to define notes for each component (usually you want the generated readme)
- live rebuild/reload of stencil components (it's still a little wonky - sometimes you have to refresh the browser)
- also comes with the viewport add-on
Setup
To get this repo running locally so you can modify existing components or create new ones, install the dependencies:
npm install
To see your component in Stencil's local dev server, put it in src/index.html
and start the server:
npm run start
To start storybook locally and browse through the stories:
npm run storybook
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.
Creating/Modifying a Component
Components live in the src/components
directory, and each component directory might have 6 files in it:
- The component definition
- The component CSS
- The Story for the component
- A generated readme
- End-to-End tests (testing the component from a consumer perspective)
- Unit tests (testing things within the component)
Stencil requires components to be written in TypeScript, so the definition file must end in .tsx
.
It's a good idea to have some basic tests for your new component/feature.
You can also check out the Stencil docs on creating a component here.
Naming Components
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!
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
.
Using a Component elsewhere
Publishing
This component library is meant to be able to be used on other sites. To do so, any changes to the components must be published:
npm run build
npm publish --public
Installing & Importing
First, the library must be installed:
npm install @adhocteam/component-library --save
Next, put the following code into your app's index.js
file or equivalent:
import {defineCustomElements} from '@adhocteam/component-library/loader';
defineCustomelements(window);
Alternatively, you can add a <script>
tag to your HTML:
<script src="https://unpkg.com/@adhocteam/component-library/dist/component-library.js"></script>
Using a component
If the library has been installed and imported correctly, you should be able to use one of the defined components anywhere in your HTML or JSX.