Contributing to the Metecho Component Library¶
The Metecho component library is a source for developers and non-developers alike to get a quick overview of how components that make up the project behave and appear.
Components used in the project are custom versions of SLDS components.
The library was created with Storybook and is deployed using Storybook Deployer.
Component Library Structure¶
Components for the library are located in src/stories/
in folders organized
similarly to how the original components are organized in src/js/components
.
For example, the component library version of the modal for creating a new
Epic, the createForm
component, would be found in the epics/
directory:
src/
stories/
epics/
createForm/
index.stories.mdx
index.stories.tsx
Each component folder consists of two files. The .mdx
file is where
documentation for each component is stored. The rendering of the component, with
all of its relevant states, is located in the .tsx
file.
Rendering Components¶
To render a component, follow the the general Storybook steps for configuring a story.
In general, this consists of:
Importing the component from
src/js/components
Setting where and how Storybook lists the component with a default export
Creating a template for how
args
map to renderingSetting the component
args
andargTypes
Naming the component story by setting a
storyName
Run Component Library Locally¶
To view changes while you work on the library, use one of the below commands:
$ ./derrick storybook # to run Storybook inside a Docker container
$ yarn storybook # to run Storybook locally, outside a Docker container
After running one of these commands, you can view the library at http://localhost:6006/ in your browser.
Decorators¶
If a component relies on the Redux store, it must be wrapped in a decorator. First import the mock Redux store:
import { withRedux } from '../decorators';
and then add a decorators
prop to the default export:
export default {
title: 'Commits/List/Example',
component: CommitListComponent,
decorators: [withRedux()],
};
Sample Data¶
Some components require sample data and props to function correctly. This data,
and other required API url routes, can be found in stories/fixtures.ts
.
Storybook defaults to showing each component prop as a control for each component in the library. For this project, props that are less relevant to the various states of the component have been disabled. Props more relevant to state and display are set with appropriate control types.
Documenting Components¶
Documentation for each component is written in a separate .mdx
file. This
should at minimum consist of the following:
A header that shows the name of the component and a brief description of its role
A general overview of the component explaining its purpose and possible states
An embedded rendering of the component
Metecho-specific terms are capitalized and bolded. References to component props
and states are written as code
.
Deploying to Github Pages¶
Through Storybook Deployer,
the library is set to deploy automatically as a static site to Github Pages each
time a commit is made to the main
branch.
The workflow for this job is located in .github/workflows/deploy-storybook.yml
Additional core Storybook configuration settings (i.e. global decorators and
parameters, webpack configuration, story loading, etc.) can be found in the
.storybook/
directory.