@picter/prisma NPM

React component library for building Picter applications and user interfaces.

This repository is a collection of components implemented using React and styled-components.

Usage

Development

Usage

List of available components

View our list of components inside our online storybook.

Check usage examples clicking in a component and on a Show info button.

Component type

All Prisma components are React components composed by styled-components. We never expose our styled-components to outside of the library, this way we prevent usage errors.

Spacing

Prisma has defined spacings to keep our layouts consistent. The spacing is based on a 8pt grid:

This are the available spacing sizes defined inside Prisma's theme:

[ 0, 4, 8, 16, 24, 32, 48, 64, 128, 256, 512 ]

Its usage can be either through styled-components theme object or the grid-styled library.

Example with grid-styled:

<Box m={3} /> // generates a div with 16px of margin on each side
<Box px={10} /> // generates a div with 512px of left and right padding

Example with styled-components theme:

// generates a div with 16px of margin on each side
const Div = styled.div`
  margin: ${props => props.theme.space[3]}px;
`;

// generates a div with 512px of left and right padding
const Div = styled.div`
  padding-left: ${props => props.theme.space[10]}px;
  padding-right: ${props => props.theme.space[10]}px;
`;

This should be the only manner that spacings are used inside Prisma.

Theming

All components are developed with theming in mind. To correctly use them there should be a theme property availabe to each and every Prisma component within your application. There are two ways to achieve it:

Use `<ThemeProvider />`

Wrap the application with a ThemeProvider HOC and every styled-component automatically gets a theme property through context. Use withTheme to get the property inside normal components (not styled).

import { ThemeProvider } from 'styled-components';

const theme = {
  primaryColor: 'papayawhite',
};

ReactDOM.render(
  <ThemeProvider theme={theme}>
    <Application />
  </ThemeProvider>,
  root,
);

Use `<PrismaProvider />`

Alongside ThemeProvider Prisma has it's own provider which uses Picter's theme as default and loads all necessary fonts automatically. You can still override theme properties see.

import { PrismaProvider } from '@picter/prisma';

const theme = {
  primaryColor: 'papayawhite',
};

ReactDOM.render(
  <PrismaProvider theme={theme}>
    <Application />
  </PrismaProvider>,
  root,
);

Pass `theme` property directly to the component

import { Button } from '@picter/prisma';

const theme = {
  primaryColor: 'papayawhite',
};

ReactDOM.render(<Button theme={theme}>Click me!</Button>, root);

A list of all required theme properties is available here, use it as base for other themes.

To know more about styled components theming functionality refer to their documentation

Development

Developing with Storybook

We recommend the use of Storybook for developing components.

$ yarn # install dependencies

$ yarn storybook # run storybook server

$ yarn storybook:build # build static storybook

Open browser to http://localhost:6006/.

Developing locally

To avoid publishing this package everytime you need to develop a new component link this project locally to your NPM packages.

To check it out, you need to build and install this module in another React application. You can do that by running the following commands:

$ yarn; yarn build # inside prisma project

$ yarn link @picter/prisma # inside your React application

Project structure

Refer to this structure when developing new components or stories:

|- prisma
  |- src
    |- __story-helpers__    - helpers for building Storybook stories
    |- __test-helpers__     - test utilities
    |- components/           - visual components
      |- Button/
        |- styles/
          |- ButtonStyled.js
          |- variants.js
        |- constants.js
        |- index.js
        |- index.spec.js
        |- index.story.js
    |- layouts              - layout components
    |- redux-form           - components connected or related to redux-form
    |- themes
    |- utils
  |- stories
    |- Grid
      |- index.js
  |- ...

Develop components, write tests and specific component stories in src/components/.

Write multiple component stories in stories/.

Name files with *.story.js to import them to our Storybook.

Components naming and structure guidelines

When developing components for Prisma use the following structure for organization:

|- ...
  |- ButtonComponent/                 - folder which contains only files related to `ButtonComponent`
    |- styles/                        - styled-components folder related to the root component
      |- ButtonBase.js                - Button styled-components variations
      |- ButtonNormal.js
      |- ButtonFlat.js
      |- ButtonOutlined.js
      |- variants.js                  - properties style variants used by styled-components
    |- contants.js                    - contains property options for propTypes
    |- index.js                       - includes functionality, styled-components composition and export default
    |- index.spec.js                  - tests of `ButtonComponent` functionality and styles
    |- index.story.js                 - Storybook stories related to the component
    |- NestedComponent                - folder of nested component related to `ButtonComponent`
      |- styles/
      |- index.js
      |- index.spec.js
      |- index.story.js

Always export React components outside Prisma, never styled-components.

Grid system

Prisma component library uses grid-styled as foundation for its new grid system.

Grid-styled is a Responsive React grid system built with styled-components, making it easier to integrate with our library.

This library will be exclusive to Prisma developers, hence not be available to Prisma users.

Bear in mind:

Structural components (e.g. Container, Row, Column) should be implemented acting as an interface/wrapper around grid-styled components and be exported to be used by end users as our own grid components.
New components should use our grid components whenever it's possible, although it can rely on grid-styled for excepcional cases.

The main reason is to define constraints and not give total autonomy to application developers (Prisma users).

Refer to its documentation to learn more about it.

Docs

Site

Linting

This module has eslint configured following the pattern from eslint-config-picter.

You can run the linter with the following commands:

$ yarn lint # single run

$ yarn lint:watch # run everytime a file changes

Testing

We are using Jest and Enzyme to create unit tests. You can run tests with:

$ yarn test # single run

$ yarn test:watch # run everytime a file changes

$ yarn test:coverage # get coverage report

$ yarn test:report-coverage # upload report to coverage tool

Building

$ yarn build # single run

$ yarn build:watch # run everytime a file changes

Releasing

$ git checkout master # go to master branch

$ git pull # get latest changes

$ gi release {major|minor|patch} # using our gi-cli tool create a new PR for release

$ git tag vX.X.X # create a new tag with same version from PR

$ git push --tags # push tag to github to trigger release

# if new release is a major or minor version please specify changes inside the "Releases" tab
# enjoy

picter prisma ui-library