You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -10,268 +10,35 @@ We also have a few documents started on this subject with some helpful links and
10
10
11
11
-[Getting Started w/ React](https://gist.github.com/priley86/770aaf64ccca5bdfdb4beee208956f7b) by Patrick Riley
12
12
13
-
## Storybook
14
-
15
-
PatternFly 3 React uses React Storybook to demonstrate React UI components and patterns. You can read more about Storybook UI Development in the [Readme](https://github.com/patternfly/patternfly-react#storybook-ui-development).
16
-
17
-
After you have written your new PatternFly component, tests, and Storybook stories, please publish your Storybook for others to review it.
18
-
19
13
## PatternFly React Doc
20
14
21
-
PatternFly 4 React uses Gatsby. Examples are created to demonstrate of the use of the React components. Documents are generated from these examples.
22
15
See how to write documentation in the [`react-docs` README](./packages/react-docs/README.md)
23
16
24
-
Some things to keep in mind when writing examples:
17
+
When writing examples:
25
18
26
19
1. Keep them simple. It is much easier for a person to understand what is going on.
27
-
1. Do not do any iteration of variants, sizes, etc in the render. This is easier for the developer, but it makes it much harder to reason for the consumer.
28
-
1. Try not to add extra external dependencies. These will only be approved on a case by case basis.
29
-
1. You are unable to use experimental language features like [class properties](https://babeljs.io/docs/en/babel-plugin-proposal-class-properties) as [Buble](https://github.com/bublejs/buble) does not support them.
30
-
1. The easiest way to develop your example is by creating an empty code block and then editing it in your browser. Once your happy, copy the code back to your Markdown file.
20
+
2. Try not to add extra external dependencies. These will only be approved on a case by case basis.
31
21
32
22
## Testing
33
23
34
-
PatternFly React currently uses [Jest](https://facebook.github.io/jest/) for running snapshot tests. In the future, we will also use Airbnb's [Enzyme](http://airbnb.io/enzyme/) library. More to come soon on this topic ;-)
35
-
36
-
## Code Conventions
37
-
38
-
This section is meant to further detail some of the conventions mentioned in the Code Consistency section of the [Contributing Guide](https://github.com/patternfly/patternfly-react/blob/master/CONTRIBUTING.md#code-consistency).
39
-
40
-
PatternFly React currently uses the [Standard Javascript Style](https://standardjs.com/) and [Airbnb Style Guide](https://github.com/airbnb/javascript) rule conventions for Javascript. We've tailored many of these rules to help keep the code consistent and help ensure our continuous integration system can test rules when a pull request is opened. We've also ensured these rules work in conjunction with our auto formatter, [Prettier](https://prettier.io/).
41
-
42
-
A good percentage of the javascript rules mentioned will be automatically fixed by Prettier, so it is important to use Prettier when contributing to PatternFly React.
43
-
44
-
### Prettier
45
-
46
-
You can run the Prettier auto formatter in a few ways:
47
-
48
-
- Use your IDE and auto-format the code on save. This will likely be the most reliable option if you want immediate feedback on what the code will look like after it has been formatted as you develop. Prettier supports all of the most popular IDEs in use today. Find your IDE and install the plugin from the list of editors Prettier supports [here](https://prettier.io/docs/en/editors.html).
49
-
- Note: if you are using VSCode, we have the settings currently checked in to the project (so you will get those automatically). You can view all code formatting errors in the "Output" console of VSCode as you save and format files.
50
-
- Run the command:
51
-
- You can simply run `npm run prettier` and all code will be formatted.
52
-
53
-
The following is a breakdown of many of the Javascript rules implemented (beyond formatting rules fixed by Prettier) and how you can go about fixing them. You can find the most up to date settings on these rules in PatternFly React's [eslintrc](https://github.com/patternfly/patternfly-react/blob/master/.eslintrc).
54
-
55
-
### Eslint Rules
56
-
57
-
The following are a few of the most common lint rule issues you may encounter in PatternFly React. These notes are meant to help beginners. As always, consult the latest documentation when addressing these rules.
58
-
59
-
#### React Rules
60
-
61
-
**react/prefer-stateless-function**
62
-
63
-
First and foremost, please try to ensure all React components are stateless when possible (i.e. a component should be stateless if it does not use `this.state` or the `this` keyword). Stateless components optimize the rendering path, ensure modular design, promote good test coverage, and ensure good separation of concerns ([read more](https://hackernoon.com/react-stateless-functional-components-nine-wins-you-might-have-overlooked-997b0d933dbc) on why stateless components are preferred). When possible, you should always "[lift state](https://reactjs.org/docs/lifting-state-up.html)" to the closest common ancestor. This is a core tenant of React and ensures a reduced surface area for bugs.
64
-
65
-
Example bad:
66
-
67
-
```
68
-
class ComponentA extends React.Component {
69
-
render(){
70
-
const {name} = this.props;
71
-
return (<p> Hello {name}, you are Stateful!</p>)
72
-
}
73
-
}
74
-
```
75
-
76
-
Example good:
77
-
78
-
```
79
-
const ComponentA = ({name, ...props}) => (
80
-
<p {...props}> Hello {name}, you are Stateless!</p>
81
-
)
82
-
```
83
-
84
-
See the following [eslint rule](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-stateless-function.md) for more details.
85
-
86
-
**react/require-default-props**
87
-
88
-
This lint rule indicates you have left out a default prop. All `propTypes` which are not marked `isRequired` should have a corresponding `defaultProp`.
See the following [eslint rule](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/require-default-props.md) for more details.
137
-
138
-
#### Eslint Rules
139
-
140
-
**one-var**
141
-
142
-
All `let`, `const` variables should be declared on separate lines:
143
-
144
-
Example bad:
145
-
146
-
```
147
-
let updatedSelectedRows, updatedRow;
148
-
```
149
-
150
-
Example good:
151
-
152
-
```
153
-
let updatedSelectedRows;
154
-
let updatedRow;
155
-
```
156
-
157
-
See the following [eslint rule](https://eslint.org/docs/rules/one-var) for more details.
158
-
159
-
**import/first**
160
-
161
-
Absolute imports should come before relative imports.
162
-
163
-
Example bad:
164
-
165
-
```
166
-
import { bindMethods } from '../../../common/helpers';
167
-
import React from 'react';
168
-
```
169
-
170
-
Example good:
171
-
172
-
```
173
-
import React from 'react';
174
-
import { bindMethods } from '../../../common/helpers';
175
-
```
176
-
177
-
See the following [eslint rule](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/first.md) for more details.
178
-
179
-
**prefer-destructuring**
180
-
181
-
ES6 gives us the ability to [destructure assignments](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment). Please prefer destructuring when possible.
182
-
183
-
Example bad:
184
-
185
-
```
186
-
const checked = event.target.checked;
187
-
```
188
-
189
-
Example good:
190
-
191
-
```
192
-
const { checked } = event.target;
193
-
```
194
-
195
-
See the following [eslint rule](https://eslint.org/docs/rules/prefer-destructuring) for more details.
196
-
197
-
**class-methods-use-this**
198
-
199
-
This rule fails when you have a class method that does not use `this` and should be marked static. All class methods should be bound to the class and use `this`.
See the following [eslint rule](https://eslint.org/docs/rules/class-methods-use-this) for more details.
228
-
229
-
**consistent-return**
230
-
231
-
All functions should consistently return a value (both JSX and non JSX functions).
232
-
233
-
Example bad:
234
-
235
-
```
236
-
<Table.Body onRow={(row, { rowIndex }) => {
237
-
switch (rowIndex) {
238
-
case 0:
239
-
return { className: 'active' };
240
-
case 2:
241
-
return { className: 'success' };
242
-
}} />
243
-
```
24
+
PatternFly React currently uses [Jest](https://facebook.github.io/jest/) for running snapshot tests and [Cypress](https://www.cypress.io/) for running integration tests.
244
25
245
-
Example good:
26
+
### Jest
246
27
247
-
```
248
-
<Table.Body onRow={(row, { rowIndex }) => {
249
-
switch (rowIndex) {
250
-
case 0:
251
-
return { className: 'active' };
252
-
case 2:
253
-
return { className: 'success' };
254
-
default:
255
-
return null;
256
-
}} />
257
-
```
28
+
Use Jest tests to capture how the DOM should look after rendering. Save Jest tests (`*.test.tsx` files) under a `__tests__` folder. The most commonly used test is to expect a rendered component to match a snapshot. You can run these with `yarn test`.
258
29
259
-
Note: You may also frequently see this rule fail when iterating with `map`. Ensure your `map` callback function returns a value.
30
+
### Cypress
260
31
261
-
See the following [eslint rule](https://eslint.org/docs/rules/consistent-return) for more details.
32
+
Use Cypress tests to capture how the DOM should look after interactions. Save Cypress tests (`*.spec.ts` files) under `packages/react-integration/cypress/integration`. You can run these with `yarn start:cypress`.
262
33
263
-
**no-restricted-globals**
34
+
## Linting
264
35
265
-
Example bad:
36
+
PatternFly React has 3 linters you can run all at once using `yarn lint:all`. These are run in `--fix` mode in on your staged files each commit.
266
37
267
-
```
268
-
!isNaN(value)
269
-
```
38
+
### ESLint
270
39
271
-
Example good:
40
+
ESLint is run on .js, .jsx, .ts, and .tsx files. It uses the [@typescript-eslint](https://github.com/typescript-eslint/typescript-eslint) parser with custom config added over the years. We write some of our own ESLint rules in `eslint-plugin-patternfly-react`. You can run this linter with `yarn lint:ts` or on specific files with `yarn lint <path>`.
272
41
273
-
```
274
-
!Number.isNaN(value)
275
-
```
42
+
### Version lint
276
43
277
-
See the following [eslint rule](https://eslint.org/docs/rules/no-restricted-globals) for more details.
44
+
The `@patternfly` version linter is run on all `package.json` files to ensure that versions of all `@patternfly/*` packages match. This is done to prevent mismatching versions of essential PatternFly packages from accidentally being published. You can run this linter with `yarn lint:versions`.
This project uses [theme-patternfly-org](https://github.com/patternfly/patternfly-org/tree/master/packages/theme-patternfly-org) to render example MD files.
4
4
5
-
Gatsby recursively scans all `../../patternfly-4` directories for *.md files. Your Markdown file can have the following frontmatter:
6
-
```
5
+
## Writing an MD file
6
+
7
+
Include an `id` and `section` in the frontmatter:
8
+
```yaml
7
9
---
8
-
id: '(required) title of the page'
9
-
cssPrefix: '(optional) the cssPrefix from @patternfly/patternfly (i.e. pf-c-nav)'
10
-
section: '(optional, default=components) the section the page should be generated under'
11
-
fullscreen: (optional, default=false) if the page should be rendered as-is
10
+
id: Your page title
11
+
section: components
12
12
---
13
13
```
14
14
15
-
Your Markdown file will have its JS code blocks converted to live-editable components via [`react-live`](https://github.com/FormidableLabs/react-live):
16
-
`````
17
-
18
-
import { requiredDeps } from '@patternfly/any-webpack-alias-in-gatsby-node.js'
19
-
import localDep from './examples/exampleDep.js'
20
-
21
-
## Examples
22
-
### Title describing example
15
+
Include JS code blocks:
16
+
``````md
17
+
### Your example title
23
18
```js
24
-
<p>Hello, world!</p>
25
-
```
26
-
`````
27
-
28
-
Remember that you are unable to use experimental language features like [class properties](https://babeljs.io/docs/en/babel-plugin-proposal-class-properties) as [Buble](https://github.com/bublejs/buble) does not support them.
29
-
30
-
## About Gatsby
19
+
import React from 'react';
20
+
import { YourComponent } from '@patternfly/react-core';
31
21
32
-
Gatsby is a static site generator that doubles as a hot-module reloader for building our docs. This is an grandious way to use our own components in our docs.
33
-
34
-
We have to more or less build our own version of [React Styleguidist](https://github.com/styleguidist/react-styleguidist). We can't just use [React Styleguidist](https://github.com/styleguidist/react-styleguidist) because [patternfly-next](https://github.com/patternfly/patternfly-next) and [patternfly-org](https://github.com/patternfly/patternfly-org) also uses Gatsby for their docs and the two are currently being merged and styled at [v2.patternfly.org](v2.patternfly.org).
35
-
36
-
1.**`gatsby-config.js`**: This is the main configuration file for a Gatsby site. This is where we which Gatsby plugins to include. (Check out the [config docs](https://www.gatsbyjs.org/docs/gatsby-config/) for more detail).
37
-
- We include our own plugin `gatsby-transformer-react-docgen-typescript` for transforming component source files into metadata via [React Docgen](https://github.com/reactjs/react-docgen) and [React Docgen Typescript](https://github.com/styleguidist/react-docgen-typescript).
38
-
- We use `gatsby-mdx` to parse the *.md files into React Functional Components. We use the generated HTML _except for in <code> tags_, where we instead use our own `components/componentDocs/liveEdit.js` component.
39
-
40
-
2.**`gatsby-node.js`**: This file is the secondary copnfiguration file for a Gatsby site. It expects usage of the [Gatsby Node APIs](https://www.gatsbyjs.org/docs/node-apis/). We use it just to enumerate which pages to create based off of data loaded from the `gatsby-transformer-remark` plugin.
41
-
42
-
3.**`gatsby-browser.js`**: This file is where Gatsby expects to find any usage of the [Gatsby browser APIs](https://www.gatsbyjs.org/docs/browser-apis/) (if any).
43
-
44
-
45
-
You will most likely **NOT** learn Gatsby just by reading our code. Instead, **for most developers, we recommend starting with our [in-depth tutorial for creating a site with Gatsby](https://www.gatsbyjs.org/tutorial/).** It starts with zero assumptions about your level of ability and walks through every step of the process quite quickly.
0 commit comments