Authoring new components

We use Stencil to build components, so refer to the documentation there for topics specific to Stencil.

This guide will take you through the steps required to create a new component from scratch.

Setup

First of all, clone this repository and initialize it. You will need to use aws-vault to access some secrets required to build.

Next, start the design system documentation in developer mode, so you can see your new component live. This will do an initial build before powering up vite.

The design system will start and be available to see at http://local.funnel-dev.team:3000

Create a new component

Use stencil to generate a new component. We will create a new component called fun-example:

This will create a new folder called fun-example containing the component fun-example.tsx, a css file fun-example.css, and possibly some tests, depending on the options you selected.

Paste this into the .tsx file:

Styling with Tailwind

Web components using the shadow DOM, like our web components do by default, have their style embedded in and scoped to the component, meaning each component must have it’s own style. When developing components with Stencil the component style lives in a file called fun-example.css and is compiled into the component by Stencil at build time. This css file will already have been created by Stencil when we generated the component.

In Gunnel, We use Tailwind for styling to re-use our colours, sizes, etc from our styles package in our components and to give you the benefits of Tailwind’s utility class system. Our Stencil configuration is already set up to handle this!

Paste this into your fun-example.css file:

Building it

Now we have all we need, so we can run the Stencil compiler and see the results. We have make targets to simplify this. The safest way to ensure everything is compiled properly is to run:

This will have:

• Compiled the component and updated the built packages
• Updated the react-components package to include the new component, called FunExample
• Generated a page in the design-system package called fun-example.mdx, which you can find in your local design system

You can see all the changes in git.

Monitoring for changes

When developing components it’s usually a good idea to rebuild automatically when ever a change is made:

Documentation

Documentation is written as JSDoc comments in the component itself. From there, component documentation in Gunnel is generated automatically. Because of this, it is important that the component comments are complete and thorough.

Required comments

• All components must have a header comment. This must include tags to describe slots. See ‘Supported tags’ below.
• All Props must have a comment.
• All Events must have a comment.

Supported tags

@Deprecated

Use this if the component should no longer be used. The comment should give the reason for the deprecation.

@slot

Component slots should be documented in the main component comment.

@part

Component parts should be documented in the main component comment.

@example

Content here will be converted to a live code example when the documentation is generated.

@docpath

Use this to put the component documentation in a sub-folder, for instance @docpath buttons will put the component documentation in /components/buttons/.