react-common-ts

Setup

We highly recommend nvm https://github.com/nvm-sh/nvm

1 - Go terminal and type nvm use otherwise you should use node v12

2 - yarn install

3 - yarn setup

Component playground

yarn storybook

How to use Styles in a Project

• Import StylesProvider component.
• Wrap your root component with this provider like so:

import { StylesProvider } from 'react-common-ts';

<StylesProvider>
  <App />
</StylesProvider>;

Doing this you will get the global styles setup and also access to theme specific configuration variables.

Contributing

Migrating from react-common

Consider doing the following when migrating components:

• Transform .js and .jsx to .ts and .tsx respectively.
• Remove PropTypes usage in favour of Types.
• Add comments for each prop so that storybook can take it as a docstring and show it as a description.
• Move the styles from SASS to styled-components inside your component file.
• Sometimes is not possible to move every style to styled-components, in that case don't include SASS files inside your component. Instead let the end user to do so when using your component. For storybook purposes you can add the route to your SASS file inside src/index.scss.
• Also see considerations for Creating new components.

Creating new components

Considerations:

• Export the component as default.
• Each component will live in its own folder inside ./src/components
• Shape of a component's folder
  • index.tsx where the component lives.
  • index.module.scss styles that can't be migrated to styled components.
  • ComponentName.stories.mdx storybook markup file.
  • ComponentName.spec.tsx Jest test file.

    If you need to split the component definition in several files, create one child folder for each subcomponent. Each folder should follow the same shape.

• Export your component in src/index.ts.
• Avoid using class names for styling purposes, instead use styled-components.
• When using styled-components we aim to use css tag. You can find a good example of how to implement styled components and mixins in this PR.

Migrating from ipsy-core-styles

Motivation

We want to move away from ipsp-core-styles and embrace css-in-js, reason: see css support section in nextjs repo.

General Approach

Most react-common components convert boolean props to classnames for rendering different style variants/states. We would like their typescript versions to accept similar sets of props but no more ipsy-core-styles classnames, instead use styled-components to conditional include styles as per boolean props.

Caveats

1. Comply with style guides: If there is any style conflicts between react-common code and style guides, we should respect style guides, we can also reach out to designers for details. Ask for help in #design slack channel.

2. Refer to storybook: In react-common repo, the main sass file(Button component for example: _button.sass) may contain many unused or unrelated sass code, refer to storybook and style guide to focus on necessary parts.

3. Correct storybook: Meanwhile, the main sass file may not contain all related styles (in Button component, for example, there is a line-height definition nested inside _typography.scss .ux class), make sure components are wrapped with necessary global classes in react-common storybook to find them out.

4. Migrate nested styles last: Nested styles mean a prop may not take effect without another prop, which can be confusing. Migrate the outermost styles first, then one layer nested styles, until the innermost styles, like BFS traverse.

5. Modify prop names if necessary: If a prop associated variant/state is not used anymore(no example in style guide or storybook), feel free to remove it. And if a prop name doesn't match style guide, modify it. But don't forget to add notes to ts storybook Breaking changes section.

Typical Workflow

1. Make sure to create dir, files and add exports to main entry, as per Creating new components section.

2. Switch to react-common repo, find base styles first by looking into imported sass file, storybook and zeplin style guide (if present), then add to react-common-ts repo.

3. Repeat step 2 for each variant/state, from outermost styles to innermost nested styles, If there is any style conflict between js repo and style guides, comply with style guides or ask designer.

Writing stories with Storybook

Storybook uses mdx syntax to define its stories. Is like markdown with JSX support.

Here you have a template:

import { Meta, Story, Preview, Props } from '@storybook/addon-docs/blocks';
import { action } from '@storybook/addon-actions';

import { StylesProvider } from '../../styles/global';
import MyComponent from '.';

<Meta title="MyComponent" component={MyComponent} />

# MyComponent

MyComponent component

## Props

<Props of={MyComponent} />

## Examples

<Preview>
  <Story
    name="My story"
    decorators={[
      (storyFn) => (
        <StylesProvider>
          <div style={{ padding: 25, background: 'white' }}>{storyFn()}</div>
        </StylesProvider>
      ),
    ]}
  >
    <MyComponent />
  </Story>
</Preview>

Testing

We have 2 ways of test that are complementary between them.

Snapshots

When the test runs creates an snapshot of the generated code. This snapshot will be tested against future changes in order to check if some unvoluntary change has been made.

it('renders without crashing', () => {
  const { container } = renderWithTheme(
    <Carousel layout="MOBILE">{content}</Carousel>
  );
  expect(container).toMatchSnapshot();
});

Note: This also generates snapshot of styles when working with styled components.

@testing-library/react

This package allows to create complex tests easily, and encourages good testing practices. You can find docs and samples here.

Note: when writing test suites have a11y in mind.

Release Process (versioning)

We use semantic versioning.

1. Once your PR gets approved, make sure version inside package.json is bumped before merging.
2. After merging, fetch and checkout latest master branch on local.
3. Create a tag: git tag -a vX.X.X -m "message".
4. Push the created tag to remote: git push --tags.
5. Create a release here. Link it to your recently created tag.

Releases should have a meaningful title following this recommended pattern Fix: [APPS-XXXX] Ticket title or Feature: [APPS-XXXX] Ticket title.