Benefits Data Trust Component Library

About

The BDT component library is intended to provide a solid foundation of reusable and composable UI components from which to build front end BDT applications.

• By "solid," we mean that the components are highly reliable, in that breaking changes are as infrequent as possible and managed carefully with semver, and that they are well-tested and coded.
• By "reusable," we mean that the components are intended to serve as basic building blocks that we can employ multiple times in multiple applications
• By "composable," we mean that we keep components as small and single-purpose as possible. When each component is specific and makes very few assumptions about its use, it allows us to build larger sets out of the smaller pieces we've created.

Ex:

<Section>
  <List>
    <ListItem><Link>foo</Link></ListItem>
    <ListItem><Typography>bar</Typography></ListItem>
    <ListItem>baz</ListItem>
    <ListItem><Button>qux</Button></ListItem>
  </List>
</Section>

As opposed to:

<Section
  listComponent={List}
  list={[
    {
      type: "link",
      text: "foo"
    },
    {
      type: "text",
      text: "bar"
    },
    {
      type: "none",
      text: "bar"
    },
    {
      type: "button",
      text: "qux"
    }
    ]}
/>

In the second case, the API is doing too much work to contain too much functionality. It is difficult to modify, reuse, and build larger components in unexpected ways. For example, what it we wanted to use nested sections and lists? In the first, we can mix and match at will because none of the components makes any assumptions about its children, and it is more clear how it can be used from just the basic knowledge of the component name and purpose.

Multi-package mono repo

In order to allow components and packages to be updated regularly without forcing an update to the entire library (risking a lot of breakage in the process), we structure the project as a mono repo with many packages, where each component is its own package. What this means is that the components are added to package.json separately:

devDependencies": {
  "@bdtrust-component-library/accordion": "^1.8.7",
  "@bdtrust-component-library/button": "^2.0.1",
  "@bdtrust-component-library/label": "3.5.0",
  ...
}

import Accordion from '@bdtrust-component-library/accordion';
import Button from '@bdtrust-component-library/button';
import Label from '@bdtrust-component-library/label';

In order to allow us to manage multiple versions/packages within a single repo, we use lerna. It also allows for us to add other tools to help automate the process, if we so choose.

See the following links for additional information and the how and why:

• https://blog.bitsrc.io/versioning-independent-ui-components-why-and-how-7ea60d8be5f2
• https://www.devbridge.com/articles/a-step-by-step-build-to-build-a-sharable-components-library/
• https://dev.to/jody/using-lerna-to-manage-your-javascript-monorepo-4eoo

First time setup

1. Use only yarn for running scripts, in order to avoid some unexpected conflicts with different .lock files.
2. Run npx lerna bootstrap command to install dependencies across all packages.
3. Run yarn start to start Storybook and review components.

Development

1. If using the component generator (to create a simple scaffolding with all the right files in place), you must install yeoman globally:

   npm install -g yo
   npm link generator-component

2. Run yarn create:component. You will be prompted for the component name. Enter for instance Accordion (make sure it is camel cased) and the generator script will create a new component under src with all the right files in place (component, index file, story for storybook and test file).
3. Customize the component to your liking. It is always a good idea to have at least one test that makes sure the component actually renders (using react testing library is preferred for consistency). The index.ts should not have to be modified as it exports the component and its types only.
4. If you want to add a package to all packages without running separate yarn commands, you can use npx lerna package-name --dev.

Styling

1. The styling scaffolding is done with the help of Tailwind CSS, a utility library that adds consistency for the design system. The configuration file is tailwind.config.js and contains our theme information overrides/custom values (global variables for spacing, typography etc). The default values can be found here.
2. The library uses CSS Modules in order to scope the css.
3. These values are imported in src/base.css and are shared through all components.
4. Each component can use any of the tailwind classes with the @apply rule in the component's .module.css, along with additional css not handled by Tailwind.

Publishing

Note: Publishing means a number of things here:

1. Pushing to master
2. Pushing a new tag
3. Create a release in github with change notes (and API documentation if it introduces a new component or updates an old one)
4. Publishing the scoped package to npm

Note: Before publishing packages, you must have an npm account and be added to the organization in order to publish scoped packages. If you are publishing a new scoped package, you may need to use the official BDT npm user account/email.

When publishing component, we need to make sure we are using the latest, safest code. This means that we need to have master up to date and that no test are failing.

1. Make sure develop branch is up to date with your local changes.
2. Run yarn safe-commit to run all the tests one last time.
3. Run git checkout master && git merge develop to update master branch.
4. If this is the first time publishing a new package, run npm publish --access public, create a new tag, and push it to origin master.
5. Run npx lerna publish to publish any existing packages that have been updated You will be asked for a version. Use semver best practices [semver.org][https://semver.org/]. This will automatically update your package.json to bump the version and create and push tags to GitHub. It will then publish the package to npm. All done!
6. Once published, all changes will be updated in public storybook.
7. Make sure to update develop branch with release tag commit when finished publishing.
8. Add release notes in github, as copious as necessary Releases (many projects will be relying on these to determine if there are any breaking changes).

IDE Setup

If needed/wanted, it is possible to configure your IDE to recognize tailwind custom atImports (@tailwind, @apply, @variants, @responsive, @screen). See this link for an example.

Additionally, if using VSCode, Tailwind CSS IntelliSense is helpful to get name completion while developing.