React component library for building Picter applications and user interfaces.
This repository is a collection of components implemented using
[React](https://reactjs.org/) and
[styled-components](https://www.styled-components.com/).
#### Contents
> Usage
* [List of available components](#list-of-available-components)
* [Spacing](#spacing)
* [Theming](#theming)
> Development
* [Developing with Storybook](#developing-with-storybook)
* [Developing locally](#developing-locally)
* [Project structure](#project-structure)
* [Components naming and structure guidelines](#components-naming-and-structure-guidelines)
* [Grid system](#grid-system)
* [Linting](#linting)
* [Testing](#testing)
* [Building](#building)
## Usage
### List of available components
View our list of components inside our
[online storybook](https://picter.github.io/prisma).
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:
* https://spec.fm/specifics/8-pt-grid
* https://builttoadapt.io/intro-to-the-8-point-grid-system-d2573cde8632
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](https://github.com/jxnblk/grid-styled#margin-and-padding-props):
```jsx
// generates a div with 16px of margin on each side
// generates a div with 512px of left and right padding
```
Example with styled-components theme:
```javascript
// 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 ``
Wrap the application with a `ThemeProvider` HOC and every styled-component
automatically gets a `theme` property through context. Use
[`withTheme`](https://www.styled-components.com/docs/advanced#getting-the-theme-without-styled-components)
to get the property inside normal components (not styled).
```javascript
import { ThemeProvider } from 'styled-components';
const theme = {
primaryColor: 'papayawhite',
};
ReactDOM.render(
,
root,
);
```
#### Use [``](https://github.com/picter/prisma/blob/master/src/utils/PrismaProvider/index.js)
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](https://github.com/picter/prisma/blob/master/src/themes/picter.js).
```javascript
import { PrismaProvider } from '@picter/prisma';
const theme = {
primaryColor: 'papayawhite',
};
ReactDOM.render(
,
root,
);
```
#### Pass `theme` property directly to the component
```javascript
import { Button } from '@picter/prisma';
const theme = {
primaryColor: 'papayawhite',
};
ReactDOM.render(, root);
```
A list of all required theme properties is available
[here](https://github.com/picter/prisma/blob/master/src/themes/picter.js),
use it as base for other themes.
To know more about styled components theming functionality refer to their
[documentation](https://www.styled-components.com/docs/advanced#theming)
## Development
### Developing with Storybook
We recommend the use of [Storybook](https://github.com/storybooks/storybook) for
developing components.
```bash
$ 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:
```bash
$ 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](https://github.com/jxnblk/grid-styled)
[Site](http://jxnblk.com/grid-styled)
### Linting
This module has eslint configured following the pattern from
[eslint-config-picter](https://www.npmjs.com/package/eslint-config-picter).
You can run the linter with the following commands:
```bash
$ yarn lint # single run
$ yarn lint:watch # run everytime a file changes
```
### Testing
We are using [Jest](https://facebook.github.io/jest/) and
[Enzyme](airbnb.io/enzyme) to create unit tests. You can run tests with:
```bash
$ 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
```bash
$ yarn build # single run
$ yarn build:watch # run everytime a file changes
```
### Releasing
```bash
$ 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
```
---
_Source: https://npm.io/package/@picter/prisma · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
