Reusable React components for SendGrid's applications
Switch branches/tags
Clone or download
sendgrid-ci
sendgrid-ci v1.8.4 [skip ci]
Latest commit 9583d64 Sep 20, 2018
Permalink
Failed to load latest commit information.
.buildkite Updated the buildkite README to document what we did in the pipeline … Jul 24, 2018
.storybook add some examples of how to use react-select (#147) Jul 10, 2018
.vscode Mcfe 417: Percentage Input (#233) Aug 21, 2018
ISSUE_TEMPLATE Add CONTRIBUTING and templates, closes #95 (#99) Feb 12, 2018
docs [Prepublish Built] Sep 20, 2018
packages/ui-components v1.8.4 [skip ci] Sep 20, 2018
src fix: unsaved changes only on emailcard (#262) Sep 20, 2018
stories fix: unsaved changes only on emailcard (#262) Sep 20, 2018
storybook-static Include TypeScript typings in build process #patch (#129) Apr 24, 2018
test fix: unsaved changes only on emailcard (#262) Sep 20, 2018
test_image fix: unsaved changes only on emailcard (#262) Sep 20, 2018
.babelrc feat: adds storysource (#155) #patch Jun 5, 2018
.dockerignore Dockerfile fixes to have a default command and a development mode. #m… Oct 31, 2017
.gitignore Add styleguide via sass modules #minor (#141) Jun 18, 2018
.jenkins-docker Create buildkite files #patch (#120) Mar 30, 2018
.npmignore Adds .npmignore and removes testing as a precommit hook. Also adds a … Dec 7, 2017
.prettierrc.js Add styleguide via sass modules #minor (#141) Jun 18, 2018
CHANGELOG.md Full page modal header content #minor (#255) Sep 14, 2018
CONTRIBUTING.md Add Alan to RAPID framework Jul 31, 2018
Dockerfile Fixed dockerfile to contain git (#182) Jun 19, 2018
LICENSE Initial commit Apr 24, 2017
PULL_REQUEST_TEMPLATE.md Update PULL_REQUEST_TEMPLATE.md Apr 25, 2018
README.md Patch icon types (#252) Sep 9, 2018
build.js Add styleguide via sass modules #minor (#141) Jun 18, 2018
copyStyles.sh Update copyStyles.sh Sep 18, 2018
docker-compose.yml Add styleguide via sass modules #minor (#141) Jun 18, 2018
imageSnapshot.sh Add image storyshots - kind of WIP (#158) #patch Jun 13, 2018
jest.config.js Add image storyshots - kind of WIP (#158) #patch Jun 13, 2018
jestSetup.js feat(modals): switch center and side modal to use createPortal #patch ( Apr 24, 2018
lerna.json v1.8.4 [skip ci] Sep 20, 2018
package.json Patch icon types (#252) Sep 9, 2018
tsconfig.json Mcfe 417: Percentage Input (#233) Aug 21, 2018
tslint.json Add styleguide via sass modules #minor (#141) Jun 18, 2018
updateIconTypes.sh Patch icon types (#252) Sep 9, 2018
webpack.config.js MCFE-329 modifies build process to accomodate use in other sendgrid a… Jul 2, 2018
yarn.lock Mcfe 415: Color Palette (#235) Aug 27, 2018

README.md

UI Components

Re-useable React components based on the SendGrid's Style Guide. Hosted StoryBook

Getting Started

npm install @sendgrid/ui-components

Using your local UI-components in your project

cd ~/ui-components/packages/ui-components
yarn link
> info You can now run `yarn link "@sendgrid/ui-components"` in the projects where you want to use this package and it will be used instead.
cd ~/ui-components/
npx tsc --newline lf --watch
cd ~/myCoolProject/
yarn link "@sendgrid/ui-components"

Importing UI Components into Your Project

To import the component on your desired page:

import { Badge } from '@sendgrid/ui-components';

List of available components in Available Components section.

Importing a Particular Component

Maybe you don't want to import all of UI Components. You can import just the components that you need.

import Badge from '@sendgrid/ui-components/badge';

Getting Styles to Work

UI-Components uses a mix of module styles and global styles to insert style guide. To use module styles for each individual component, you'll need to update your webpack config to parse module styles from files with the naming convention ".module.scss".

config.module.rules.push({
  test: /\.module.scss$/,
  use: [
    require.resolve('style-loader'),
    {
      loader: require.resolve('css-loader'),
      options: {
        sourceMap: true,
        importLoaders: 1,
        modules: true,
        localIdentName: '[name]__[local]___[hash:base64:5]',
      },
    },
    {
      loader: require.resolve('sass-loader'),
      options: {
        sourceMap: true,
        modules: true,
        importLoaders: 1,
        localIdentName: '[name]__[local]___[hash:base64:5]',
      },
    },
  ],
});

To use the global application styles included with styleguide (such as typography, reset, tables, and more), you'll need to include the following in your root component:

import '../path_to_uicomponents/packages/styles/global/main.scss';

Starting Storybook

After running npm install and ensuring that style-guide is pulled properly just run npm run storybook and you should be good to go!

Adding Test Hooks

For many components, it's useful for testing to have attributes that make them easy to query for and select.

For this, use attributes={{'data-test':"some-test-id}}" as an attribute that describes the component. If it's possible, you can and should the props passed in to create a unique identifier.

What are these Stateful Components?

State is hard and all of the UI components should be purely presentational. But, that makes them hard to test out in Storybook. The stateful components (e.g. StatefulTextInput) are solely for working with Storybook and are not supported or endorsed in anyway. Think of them as a private API. They can be removed at any time. You've been warned.

Semver Versioning

When making a pull request, make sure the title has a semver bump level defined (#major, #minor, or #patch).

Semver bumps are used to know when to update the @sendgrid/ui-components npm package. Patch and minor changes will be updated automatically, but major changes will update if you update your npm package version manually.

More information: https://semver.org/

Available Commands

  • yarn start: This is an alias for yarn run storybook
  • yarn storybook: Start Storybook on port 6006.
  • yarn build: Builds the assets for deployment.
  • yarn lint: Runs the linter.
  • yarn lint-fix: Runs the linter and auto-fixes the errors it can auto-fix.
  • yarn test: Run the unit tests.
  • yarn snapshot: Update snapshot tests. Make sure you run the tests first and you're not overwriting snapshots by accident.
  • yarn lint-snapshot: A combination of yarn run lint and yarn run snapshot.
  • yarn ci-test: Test used for the CI build (doesn't use interactive mode).
  • yarn build-storybook: Build a deployable version of the Storybook.
  • yarn prepare: Used by npm to build the assets before publishing.
  • yarn run image-snapshots: Builds a static index.html file and runs image snapshot tests.
  • yarn update-icon-types: Pull latest styleguide css and update the types of icon to match all found instances of sg-icon-${type}

Testing

To make sure your additions don't break ui-components, run npm run test, which will test all of your changed *.test.* files and show a coverage report. To check image snapshots run npm run image-snapshots updating and other commands can be passed through to jest like npm run image-snapshots -u.

Image Snapshots & Docker:

  • Since we run image snapshots in Buildkite with docker we need to run them locally with docker as well because different Os's render fonts and other things differently. We don't publish our docker image so you'll have to build and re-build the image any time our dependencies change in package.json. To do so just run the command docker-compose build build. This should build the container and be ready to run.

Image Snapshots & Animations:

  • We add a css rule in storybook when we detect the file:// pattern that disables all animations on the page so we can get consistent image snapshots with animations

Contributing

See CONTRIBUTING.md

Deploying

Visit the Buildkite Master Branch and select the SemVer appropriate to your deployment and you should be off and away. Make sure to post in FE Guild that a new version is going out.