0.0.34 • Published 4 years ago

@tt92618/component-library-react v0.0.34

Weekly downloads
-
License
ISC
Repository
github
Last release
4 years ago

OpenMarket Component Library

Table of Contents

Contributing Guidelines

Branch naming conventions

  • master
  • feature/JIRA#/DESCRIPTION
    • ex: feature/OMPUX-123/button
  • bug/JIRA#/DESCRIPTION
    • ex: bug/OMPUX-123/button-focus-state
  • hotfix/JIRA#/DESCRIPTION
  • tech/DESCRIPTION
    • ex: updating prettier config
    • used for devops or internal tasks not related to features

PR review process

  • Once a PR is ready for review, the author will add peer reviewers in GitLab.
    • Reviewers should receive notifications about PRs that are ready to review through email once they are added on GitLab. If necessary, the author can also ping assigned reviewers in slack.
  • Once the PR has two approvals, the code can be merged. The author of the PR should be the one to merge the PR.

QA Process

  • dev pushes branch for peer review

  • after 2 reviewers have approved and merged, story moves into QA status in Jira

  • QA dev tests the component locally.

  • Once complete, QA changes the Storybook Meta Tag (see examples below) and pushes a new PR for review

    • <Meta title='4 In Progress / Card' component={Card} />

    • <Meta title='3 Components / Card' component={Card} />

  • Once merged, the story is now complete – “dev done”

Code coverage & Testing

We have global test coverage rules in place to ensure that code is properly tested. The guidelines are as follows:

global: {
  branches: 90,
  functions: 90,
  lines: 90,
  statements: -10
}

For more information about testing frameworks etc see the testing section below.

Dependencies

  • NodeJS
  • NPM
  • @emotion/core
  • react
  • react-dom
  • emotion-theming

For more information, see 'Getting Started' below.

Getting Started

Start by installing the node dependencies with:

> npm install

This will bring in all the needed dev and runtime dependencies. Note that this will not install peer dependencies; you must manually ensure that peer dependencies are installed. See Installing Peer Dependencies below for more information.

There are simple example components in src/components/ExampleComponent and src/styled-components/ExampleComponents which outline basic technical patterns used.

Installing Peer Dependencies

In addition to dev and runtime dependencies, this library also has a number of peer dependencies that are defined in the peerDependencies section of its package.json. These include the following:

  • @emotion/core: ^10.0.28
  • react: ^16.13.1
  • react-grid-system: ^7.1.1
  • react-dom: ^16.13.1
  • emotion-theming: ^10.0.27

You must install these peer dependencies. Not doing so will prevent the library from building locally, and storybook will not work. It will also cause failures in any application consuming the library directly. We recommend that you add these peer dependencies into the package.json of any consuming app by placing them in the peerDependencies section:

"peerDependencies": {
  "@emotion/core": "^10.0.28",
  "react": "^16.13.1",
  "react-grid-system": "^7.1.1",
  "react-dom": "^16.13.1",
  "emotion-theming": "^10.0.27"
},

Once this is done, you must then ensure they are installed. The preferred way of doing this is to use a peer dependency manager. To do so, first make sure your development environment has npm-install-peers installed globally. This may be accomplished by executing the following:

> npm install -g npm-install-peers

This will install a CLI tool allowing the easy installation or updating of any peer dependencies defined in package.json. Once installed, you may use it by executing the following:

> npm-install-peers

Please note that it is not advised that you individually install peer dependencies. From time to time, we may update existing peer dependencies, or add new ones to the library. It is most efficient for you to keep your consuming application's peerDependencies in sync, and then make ensuring their install a part of your development practice. Therefore it is advisable that you install npm-install-peers and then make a habit of first executing npm install and then executing npm-install-peers.

Storybook

This codebase uses Storybook as a sandbox to develop components. To run the Storybook, use:

> npm run storybook

This will open the sandbox site in your default browser, and automatically poll for changes. When changes occur, the site will refresh.

Storybook is useful while developing a new component but it also serves as the documentation for the entire component library. Each component has a Docs tab with the documentation for that component.

Anything inside of a <Story> tag in the component.stories.mdx file will be visible in storybook. When developing your component, make sure the story associated with it stays up to date so you can see the work you are doing in storybook.

Addons

Storybook functionality is extended through the use of addons. In this project we are using the following addons:

Docs - Automatically generates documentation for each component based on the story file. Also enables us to write more complex documentation using MDX.

a11y - Checks your stories for accessibility violations within your components.

Generating components

This codebase uses Plop.js as a foundation for generating components.

To generate a new component, use:

> npm run generate

or

> npm run g

You will be prompted to choose between a component, or a styled component. For a styled component, you will need to provide the component name as well as the element type. For components you will only be prompted for the name.

All the supporting files (types, storybook, component, test) will be created for you so that you can start developing your component without writing boilerplate code.

For components, the index.ts barrel file will be appended to include the new component so it can be exported externally.

Styling

This code base uses the Emotion library for Styled Components.

Theming

Each component has access to a base theme (located in src/themes/base) through props. An example of how to use this theme is generated with each component. This theme has all of our commonly used variables and should be used wherever appropriate.

Using theme variables where appropriate while developing components will prevent issues if the base theme needs to change. It also allows the component library to function with additional themes in the future.

Testing

Frameworks

This code base uses Jest and React Testing Library for unit testing.

Jest serves as the test runner and allows you to write readable unit tests.

React Testing Library is a very light-weight solution for testing React components. It provides light utility functions on top of react-dom and react-dom/test-utils allowing you to render and access your React components to test them with Jest.

Running the tests

To run all the unit tests a single time, use:

> npm run test

To run the unit tests in "watch mode", which will continuously poll for file changes and automatically rerun the tests upon changes, use:

> npm run test:watch

This is useful when writing tests for new components as your tests will rerun any time you save.

To run all of the tests and generate a code coverage report, use:

> npm run test:coverage

The HTML code coverage report is available via ./coverage/lcov-report/index.html. Just open in a browser and you can see the details of each file in the code base. Be sure to check your code coverage before pushing any code. Coverage needs to be at least 90%.

To update the snapshot for a failing snapshot test, use:

> npm run test:update

This applies to tests using toMatchSnapshot(). Our styled components are generated with snapshot tests already in place. These snapshots should be committed and pushed up as well. Jest will automatically create a snapshot of the styles the first time a test is run and then check against that snapshot later. Snapshots must be updated when a components' style has been intentionally changed and the snapshot no longer matches the desired style.

Linting

To run the linting and check for code quality infractions, use:

> npm run lint

Building

To build the component library, use:

> npm run build

This will run the lint task, the unit tests with coverage and build the library into the ./build directory.

For a build without code coverage or linting, use:

> npm run build:dev

It is helpful to run the build before pushing code so that you can check for any potential issues that might cause the build to fail during the CI process.

Z-index

When building components with z-index, please keep in mind the following guidelines:

Document the use of z-index in src/docs/Introduction.stories.mdx. This will allow others using z-index in the future to know what values to use. Starting with 1000 for the modal, add future components in where it makes sense dividing by half the distance each time. For items that can go over modals, go up by 100.

Example: (this is just an example - the actual numbers are documented in src/docs/Introduction.stories.mdx)

Modal - 1000 Popover - 500 System Alert - 1100 Dropdown - 250

The numbers indicate the order in which each was identified. Notice how dropdown is 250. It was identified after Popover, but it should be under on the screen, so the halfway point between 1 and 500 is 250.

Releases

Updating the version with npm version <newVersion> will trigger a release. GitLab CI is set up to deploy the documentation to GitLab pages and publish the library whenever this happens. You only need to increase the version when you want to trigger a release. We are following Semantic Versioning guidelines.

Add the following to your .gitconfig so that the postversion script can create an upstream branch:

[push]
	default = current
@popperjs/core@tt92618/custom-react-calendaruse-mask-input
0.0.34

4 years ago