@spothero/ui: SpotHero's Core React UI Component Library

This module provides your project with the core React components necessary to develop applications adhering to SpotHero's branding and code conventions.

Installation

npm install @spothero/ui -S

NOTE: Make sure to also install all the necessary peerDependencies.

Suggested Module Setup

When using some of the components here its a good idea to add a few polyfills and initialize some setup routines in your main project module.

npm install core-js regenerator-runtime transitionEnd scrollingelement -S

And in your main module:

import 'core-js/stable';
import 'regenerator-runtime/runtime';
import 'scrollingelement';
import 'transitionEnd';

Usage

After installing the module you'll have to make sure that you load the corresponding Sass into your project. You'll need to add the node_modules directory to your Sass includePaths. As an example, if using gulp-sass, your sass task should include the following:

...
    .pipe(sass({
        includePaths: ['node_modules']
    }))
...

Import the Sass module into your main Sass file:

...
@import "@spothero/ui/styles/index";
...

You can now use the modules in your JS.

...
import Button from '@spothero/ui/button';
...

Local Development

The process for local development on this package is simple.

npm install
npm start

This will spin up a Storybook instance as well as open the Cypress app. The reason for this is so that you get to develop the components while at the same time running the test suite against them to make sure no regressions are introduced.

Adding New UI Components

1. Create a directory in src with the same name as the component.
2. Create the properly named component .jsx and .scss files for the component. Ensure that the Sass file is a partial (starts with _, i.e. _Foo.scss) so that it doesn't get compiled separately.
3. Add the Sass partial import to src/_index.scss.
4. Add the React component export to src/index.js.
5. Document all PropTypes and public methods accordingly so that they show up in the Storybook documentation properly.
6. Add a /stories directory that has any/all usage examples for the component functionality. Follow the conventions outlined in the other components to do this.
7. Submit a pull request with your changes.
8. Publish a new version. See Building a New Version.
   1. This will also automatically publish an updated version of the style guide.

As an example, a component named Foo should have the following file structure:

├── fe-ui
|   └── src
|       └── Foo
|           └── stories
|               ├── Display.stories.js
|               └── Colors.stories.js
|           ├── _Foo.scss
|           ├── Foo.jsx
|           └── Foo.spec.js

File changes should mimic the following:

fe-ui/src/_index.scss

...
@import "Foo/Foo";
...

fe-ui/src/index.js

...
import Foo from './Foo/Foo';

export {
    ...
    Foo,
    ...
};
...

fe-ui/src/Foo/Foo.jsx

...
// Component code above/below and PropTypes documentation example
/** Additional class(es) to add to the component. */
className: PropTypes.string,
/** Whether the component is being tested by a user. */
testing: PropTypes.bool,
/** Whether the component should be disabled. */
disabled: PropTypes.bool
...

fe-ui/src/Foo/Foo.spec.js

...
describe('<Foo />', () => {
    ...
});
...

Making UI Component Updates

You can make component updates as necessary and see your updates in real time by running the local development server using npm start.

There are a few things to remember when making updates to any modules:

1. Make your code and test changes as necessary.
2. If necessary, update/add the associated stories to ensure the Storybook is always up to date.
3. Submit a pull request with your changes.
4. Publish a new version. See Building a New Version.
   1. This will also automatically publish an updated version of the style guide.

File changes should mimic the following:

fe-ui/src/Foo/Foo.jsx

...
// PropTypes documentation example
/** Additional class(es) to add to the component. */
className: PropTypes.string,
/** Whether the component is in a loading state. */
loading: PropTypes.bool,
/** Whether the component should be disabled. */
disabled: PropTypes.bool
...

Writing Tests

UI tests are written using Cypress.

Local Testing

Follow the steps below to work on tests locally.

1. Run npm install to install the necessary dependencies.
2. You can run npm start to also open the Cypress app. You will now have full access to live regression testing as you develop.

Continuous Integration Testing

Tests can also be run as part of a continuous integration pipeline.

1. The pipeline should run npm ci to install the necessary dependencies.
   1. IMPORTANT: The environment running the tests will need to be aware of our private npm registry.
2. The pipeline can now execute npm test to run the test suite.
   1. If tests fail, the build will exit with a code of 1.

Building a New Version

See the publishing guidelines.

Publishing a New Version

• Follow Squashing Commits guidelines to merge your PR.
• Start main-npm-publish build in fe-ui Concourse CI/CD.