@entva/styleguide 0.0.0 → 2.30.0

package/react/README.md

@@ -1,726 +0,0 @@
-# React/JSX Style Guide
-
-*A mostly reasonable approach to React and JSX*
-
-This style guide is mostly based on the standards that are currently prevalent in JavaScript, although some conventions (i.e async/await or static class fields) may still be included or prohibited on a case-by-case basis. Currently, anything prior to stage 3 is not included nor recommended in this guide.
-
-## Table of Contents
-
-  1. [Basic Rules](#basic-rules)
-  1. [Hooks vs Class vs `React.createClass` vs stateless](#hooks-vs-class-vs-reactcreateclass-vs-stateless)
-  1. [Mixins](#mixins)
-  1. [Naming](#naming)
-  1. [Alignment](#alignment)
-  1. [Quotes](#quotes)
-  1. [Spacing](#spacing)
-  1. [Props](#props)
-  1. [Refs](#refs)
-  1. [Parentheses](#parentheses)
-  1. [Tags](#tags)
-  1. [Methods](#methods)
-  1. [Ordering](#ordering)
-  1. [CSS Modules](#css-modules)
-
-## Basic Rules
-
-  - Only include one React component per file.
-    - However, multiple simple [Functional](https://facebook.github.io/react/docs/reusable-components.html#stateless-functions) sub-components are allowed per file. eslint: [`react/no-multi-comp`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-multi-comp.md#ignorestateless).
-  - Always use JSX syntax.
-  - Do not use `React.createElement` unless you’re initializing the app from a file that is not JSX.
-  - [`react/forbid-prop-types`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/forbid-prop-types.md) will allow `arrays` and `objects` only if it is explicitly noted what `array` and `object` contains, using `arrayOf`, `objectOf`, or `shape`.
-
-## Hooks vs Class vs `React.createClass` vs stateless
-
-  - Prefer functional components with Hooks over `class extends React.Component` (when possible) or `React.createClass`. eslint: [`react/prefer-es6-class`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-es6-class.md) [`react/prefer-stateless-function`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-stateless-function.md)
-
-    ```jsx
-    // bad
-    const Listing = React.createClass({
-      // ...
-      render() {
-        return <div>{this.state.hello}</div>;
-      }
-    });
-
-    // better
-    class Listing extends React.Component {
-      // ...
-      render() {
-        return <div>{this.state.hello}</div>;
-      }
-    }
-    ```
-
-    And if you can accomplish the same with Hooks:
-
-    ```jsx
-    // better
-    class Listing extends React.Component {
-      render() {
-        return <div>{this.props.hello}</div>;
-      }
-    }
-
-    // best
-    const Listing = ({ hello }) => (
-      <div>{hello}</div>
-    );
-    ```
-
-## Mixins
-
-  - [Do not use mixins](https://facebook.github.io/react/blog/2016/07/13/mixins-considered-harmful.html).
-
-  > Why? It's a legacy feature not meant to be used in modern React applications.
-
-## Naming
-  - **Extensions**: Use `.jsx` extension for React components. eslint: [`react/jsx-filename-extension`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-filename-extension.md)
-  - **Filename**: Use snake_case for filenames. E.g., `reservation_card.jsx`. Why? Many OS use non case sensitive file systems by default, renaming `Myfile` to `MyFile` in case of a typo might be difficult.
-  - **Reference Naming**: Use PascalCase for React components and camelCase for their instances. eslint: [`react/jsx-pascal-case`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md)
-
-    ```jsx
-    // bad
-    import reservationCard from './reservation_card';
-
-    // good
-    import ReservationCard from './reservation_card';
-
-    // bad
-    const ReservationItem = <ReservationCard />;
-
-    // good
-    const reservationItem = <ReservationCard />;
-    ```
-
-  - **Component Naming**: Use the filename as the component name. For example, `reservation_card.jsx` should have a reference name of `ReservationCard`. However, for root components of a directory, use `index.jsx` as the filename and use the directory name as the component name:
-
-    ```jsx
-    // bad
-    import Footer from './footer/footer';
-
-    // bad
-    import Footer from './footer/index';
-
-    // good
-    import Footer from './footer';
-    ```
-
-  - **Higher-order Component Naming**: Use a composite of the higher-order component’s name and the passed-in component’s name as the `displayName` on the generated component. For example, the higher-order component `withFoo()`, when passed a component `Bar` should produce a component with a `displayName` of `withFoo(Bar)`.
-
-    > Why? A component’s `displayName` may be used by developer tools or in error messages, and having a value that clearly expresses this relationship helps people understand what is happening.
-
-    ```jsx
-    // bad
-    export default function withFoo(WrappedComponent) {
-      return function WithFoo(props) {
-        return <WrappedComponent {...props} foo />;
-      }
-    }
-
-    // good
-    export default function withFoo(WrappedComponent) {
-      function WithFoo(props) {
-        return <WrappedComponent {...props} foo />;
-      }
-
-      const wrappedComponentName = WrappedComponent.displayName
-        || WrappedComponent.name
-        || 'Component';
-
-      WithFoo.displayName = `withFoo(${wrappedComponentName})`;
-      return WithFoo;
-    }
-    ```
-
-  - **Props Naming**: Avoid using DOM component prop names for different purposes.
-
-    > Why? People expect props like `style` and `className` to mean one specific thing. Varying this API for a subset of your app makes the code less readable and less maintainable, and may cause bugs.
-
-    ```jsx
-    // bad
-    <MyComponent style="fancy" />
-
-    // bad
-    <MyComponent className="fancy" />
-
-    // good
-    <MyComponent variant="fancy" />
-    ```
-
-## Alignment
-
-  - Follow these alignment styles for JSX syntax. eslint: [`react/jsx-closing-bracket-location`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-bracket-location.md) [`react/jsx-closing-tag-location`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-tag-location.md)
-
-    ```jsx
-    // bad
-    <Foo superLongParam="bar"
-         anotherSuperLongParam="baz" />
-
-    // good
-    <Foo
-      superLongParam="bar"
-      anotherSuperLongParam="baz"
-    />
-
-    // if props fit in one line then keep it on the same line
-    <Foo bar="bar" />
-
-    // children get indented normally
-    <Foo
-      superLongParam="bar"
-      anotherSuperLongParam="baz"
-    >
-      <Quux />
-    </Foo>
-
-    // bad
-    {showButton &&
-      <Button />
-    }
-
-    // bad
-    {
-      showButton &&
-        <Button />
-    }
-
-    // good
-    {showButton && (
-      <Button />
-    )}
-
-    // good
-    {showButton && <Button />}
-    ```
-
-## Quotes
-
-  - Always use double quotes (`"`) for JSX attributes, but single quotes (`'`) for all other JS. eslint: [`jsx-quotes`](https://eslint.org/docs/rules/jsx-quotes)
-
-    > Why? Regular HTML attributes also typically use double quotes instead of single, so JSX attributes mirror this convention.
-
-    ```jsx
-    // bad
-    <Foo bar='bar' />
-
-    // good
-    <Foo bar="bar" />
-
-    // bad
-    <Foo style={{ left: "20px" }} />
-
-    // good
-    <Foo style={{ left: '20px' }} />
-    ```
-
-## Spacing
-
-  - Always include a single space in your self-closing tag. eslint: [`no-multi-spaces`](https://eslint.org/docs/rules/no-multi-spaces), [`react/jsx-tag-spacing`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-tag-spacing.md)
-
-    ```jsx
-    // bad
-    <Foo/>
-
-    // very bad
-    <Foo                 />
-
-    // bad
-    <Foo
-     />
-
-    // good
-    <Foo />
-    ```
-
-  - Do not pad JSX curly braces with spaces. eslint: [`react/jsx-curly-spacing`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-curly-spacing.md)
-
-    ```jsx
-    // bad
-    <Foo bar={ baz } />
-
-    // good
-    <Foo bar={baz} />
-    ```
-
-## Props
-
-  - Always use camelCase for prop names.
-
-    ```jsx
-    // bad
-    <Foo
-      UserName="hello"
-      phone_number={12345678}
-    />
-
-    // good
-    <Foo
-      userName="hello"
-      phoneNumber={12345678}
-    />
-    ```
-
-  - Omit the value of the prop when it is explicitly `true`. eslint: [`react/jsx-boolean-value`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-boolean-value.md)
-
-    ```jsx
-    // bad
-    <Foo
-      hidden={true}
-    />
-
-    // good
-    <Foo
-      hidden
-    />
-
-    // good
-    <Foo hidden />
-    ```
-
-  - Always include an `alt` prop on `<img>` tags. If the image is presentational, `alt` can be an empty string or the `<img>` must have `role="presentation"`. eslint: [`jsx-a11y/alt-text`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/alt-text.md)
-
-    ```jsx
-    // bad
-    <img src="hello.jpg" />
-
-    // good
-    <img src="hello.jpg" alt="Me waving hello" />
-
-    // good
-    <img src="hello.jpg" alt="" />
-
-    // good
-    <img src="hello.jpg" role="presentation" />
-    ```
-
-  - Do not use words like "image", "photo", or "picture" in `<img>` `alt` props. eslint: [`jsx-a11y/img-redundant-alt`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/img-redundant-alt.md)
-
-    > Why? Screenreaders already announce `img` elements as images, so there is no need to include this information in the alt text.
-
-    ```jsx
-    // bad
-    <img src="hello.jpg" alt="Picture of me waving hello" />
-
-    // good
-    <img src="hello.jpg" alt="Me waving hello" />
-    ```
-
-  - Use only valid, non-abstract [ARIA roles](https://www.w3.org/TR/wai-aria/#usage_intro). eslint: [`jsx-a11y/aria-role`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-role.md)
-
-    ```jsx
-    // bad - not an ARIA role
-    <div role="datepicker" />
-
-    // bad - abstract ARIA role
-    <div role="range" />
-
-    // good
-    <div role="button" />
-    ```
-
-  - Do not use `accessKey` on elements. eslint: [`jsx-a11y/no-access-key`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/no-access-key.md)
-
-  > Why? Inconsistencies between keyboard shortcuts and keyboard commands used by people using screenreaders and keyboards complicate accessibility.
-
-  ```jsx
-  // bad
-  <div accessKey="h" />
-
-  // good
-  <div />
-  ```
-
-  - Avoid using an array index as `key` prop, prefer a stable ID. eslint: [`react/no-array-index-key`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-array-index-key.md)
-
-> Why? Not using a stable ID [is an anti-pattern](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318) because it can negatively impact performance and cause issues with component state.
-
-We don’t recommend using indexes for keys if the order of items may change.
-
-  ```jsx
-  // bad
-  {todos.map((todo, index) =>
-    <Todo
-      {...todo}
-      key={index}
-    />
-  )}
-
-  // good
-  {todos.map(todo => (
-    <Todo
-      {...todo}
-      key={todo.id}
-    />
-  ))}
-  ```
-
-  - Use spread props sparingly.
-  > Why? Otherwise you’re more likely to pass unnecessary props down to components. And for React v15.6.1 and older, you could [pass invalid HTML attributes to the DOM](https://reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html).
-
-  Exceptions:
-
-  - HOCs that proxy down props and hoist propTypes
-
-  ```jsx
-  function HOC(WrappedComponent) {
-    return class Proxy extends React.Component {
-      Proxy.propTypes = {
-        text: PropTypes.string,
-        isLoading: PropTypes.bool
-      };
-
-      render() {
-        return <WrappedComponent {...this.props} />
-      }
-    }
-  }
-  ```
-
-  - Spreading objects with known, explicit props. This can be particularly useful when testing React components with Mocha’s beforeEach construct.
-
-  ```jsx
-  export default function Foo {
-    const props = {
-      text: '',
-      isPublished: false
-    }
-
-    return (<div {...props} />);
-  }
-  ```
-
-  Notes for use:
-  Filter out unnecessary props when possible. Also, use [prop-types-exact](https://www.npmjs.com/package/prop-types-exact) to help prevent bugs.
-
-  ```jsx
-  // bad
-  render() {
-    const { irrelevantProp, ...relevantProps  } = this.props;
-    return <WrappedComponent {...this.props} />
-  }
-
-  // good
-  render() {
-    const { irrelevantProp, ...relevantProps  } = this.props;
-    return <WrappedComponent {...relevantProps} />
-  }
-  ```
-
-## Refs
-
-  - Always use ref callbacks, createRef or useRef hook. eslint: [`react/no-string-refs`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-string-refs.md)
-
-    ```jsx
-    // bad
-    <Foo
-      ref="myRef"
-    />
-
-    // good
-    <Foo
-      ref={(ref) => { this.myRef = ref; }}
-    />
-    ```
-
-## Parentheses
-
-  - Wrap JSX tags in parentheses when they span more than one line. eslint: [`react/jsx-wrap-multilines`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-wrap-multilines.md)
-
-    ```jsx
-    // bad
-    render() {
-      return <MyComponent variant="long body" foo="bar">
-               <MyChild />
-             </MyComponent>;
-    }
-
-    // good
-    render() {
-      return (
-        <MyComponent variant="long body" foo="bar">
-          <MyChild />
-        </MyComponent>
-      );
-    }
-
-    // good, when single line
-    render() {
-      const body = <div>hello</div>;
-      return <MyComponent>{body}</MyComponent>;
-    }
-    ```
-
-## Tags
-
-  - Always self-close tags that have no children. eslint: [`react/self-closing-comp`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/self-closing-comp.md)
-
-    ```jsx
-    // bad
-    <Foo variant="stuff"></Foo>
-
-    // good
-    <Foo variant="stuff" />
-    ```
-
-  - If your component has multi-line properties, close its tag on a new line. eslint: [`react/jsx-closing-bracket-location`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-bracket-location.md)
-
-    ```jsx
-    // bad
-    <Foo
-      bar="bar"
-      baz="baz" />
-
-    // good
-    <Foo
-      bar="bar"
-      baz="baz"
-    />
-    ```
-
-## Methods
-  - Bind event handlers for the render method in the constructor. eslint: [`react/jsx-no-bind`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-bind.md)
-
-    > Why? A bind call in the render path creates a brand new function on every single render. Do not use arrow functions in class fields, because it makes them [challenging to test and debug, and can negatively impact performance](https://medium.com/@charpeni/arrow-functions-in-class-properties-might-not-be-as-great-as-we-think-3b3551c440b1), and because conceptually, class fields are for data, not logic.
-
-    ```jsx
-    // bad
-    class extends React.Component {
-      handleClickDiv() {
-        // do stuff
-      }
-
-      render() {
-        return <div onClick={this.handleClickDiv.bind(this)} />;
-      }
-    }
-
-    // bad
-    class extends React.Component {
-      handleClickDiv = () => {
-        // do stuff
-      }
-
-      render() {
-        return <div onClick={this.handleClickDiv} />
-      }
-    }
-
-    // good
-    class extends React.Component {
-      constructor(props) {
-        super(props);
-
-        this.handleClickDiv = this.handleClickDiv.bind(this);
-      }
-
-      handleClickDiv() {
-        // do stuff
-      }
-
-      render() {
-        return <div onClick={this.handleClickDiv} />;
-      }
-    }
-    ```
-
-  - Do not use underscore prefix for internal methods of a React component.
-    > Why? Underscore prefixes are sometimes used as a convention in other languages to denote privacy. But, unlike those languages, there is no native support for privacy in JavaScript, everything is public. Regardless of your intentions, adding underscore prefixes to your properties does not actually make them private, and any property (underscore-prefixed or not) should be treated as being public.
-
-    ```jsx
-    // bad
-    React.createClass({
-      _handleClickSubmit() {
-        // do stuff
-      },
-
-      // other stuff
-    });
-
-    // good
-    class extends React.Component {
-      handleClickSubmit() {
-        // do stuff
-      }
-
-      // other stuff
-    }
-    ```
-
-  - Prefix event handlers with `handle`
-    > Why? It helps differentiate between props and class methods.
-
-    ```jsx
-    // bad
-    class extends React.Component {
-      onClickSubmit() {
-        // do stuff
-      }
-
-      // other stuff
-    }
-
-    // good
-    class extends React.Component {
-      handleClickSubmit() {
-        // do stuff
-      }
-
-      // other stuff
-    }
-    ```
-
-  - Be sure to return a value in your `render` methods. eslint: [`react/require-render-return`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/require-render-return.md)
-
-    ```jsx
-    // bad
-    render() {
-      (<div />);
-    }
-
-    // good
-    render() {
-      return (<div />);
-    }
-    ```
-
-## Ordering
-
-  - Ordering for `class extends React.Component`:
-
-  1. `constructor`
-  1. `componentWillMount`
-  1. `componentDidMount`
-  1. `componentWillReceiveProps`
-  1. `shouldComponentUpdate`
-  1. `componentWillUpdate`
-  1. `componentDidUpdate`
-  1. `componentWillUnmount`
-  1. `getChildContext`
-  1. `getDefaultState`
-  1. *getter and setter methods`* like `getSelectReason()` or `setValue()`
-  1. *clickHandlers or eventHandlers* like `handleClickSubmit()` or `handleChangeDescription()`
-  1. *optional render methods* like `renderNavigation()` or `renderProfilePicture()`
-  1. `render`
-
-  - How to define `propTypes`, `defaultProps`, `contextTypes`, etc...
-
-    ```jsx
-    import React from 'react';
-    import PropTypes from 'prop-types';
-
-    const propTypes = {
-      id: PropTypes.number.isRequired,
-      url: PropTypes.string.isRequired,
-      text: PropTypes.string,
-    };
-
-    const defaultProps = {
-      text: 'Hello World',
-    };
-
-    class Link extends React.Component {
-      static methodsAreOk() {
-        return true;
-      }
-
-      render() {
-        return <a href={this.props.url} data-id={this.props.id}>{this.props.text}</a>;
-      }
-    }
-
-    Link.propTypes = propTypes;
-    Link.defaultProps = defaultProps;
-
-    export default Link;
-    ```
-
-## Hooks
-  Try to use functional components with Hooks whenever possible. Follow [rules of hooks](https://reactjs.org/docs/hooks-rules.html) and be aware of the need to use useMemo and useCallback to avoid unnecessary rerenders.
-
-  Pay close attention to useEffect and try to define all of the variables inside of the hook body to avoid creating
-  too many dependencies.
-
-  ```jsx
-  const Button = () => {
-    const myFn = () => {...};
-    // bad, myFn is now a dynamic dependency
-    useEffect(() => myFn(), []);
-  }
-  ```
-
-  ```jsx
-  const Button = () => {
-    // good
-    useEffect(() => {
-      const myFn = () => {...};
-      return myFn();
-    }, []);
-  }
-  ```
-
-## CSS Modules
-
-Contrary to 'global css', CSS modules do not allow overriding styles inside components out of the box.
-
-  - Use `className` prop to override styles of the root element.
-
-    ```jsx
-    // signup_button.js
-    import styles from "signup_button.module.scss"
-
-    <Button className={styles.button} />
-    ```
-
-    ```jsx
-    // button.js
-    import styles from "button.module.scss"
-
-    const Button = ({ className: passedClassName }) => {
-      const className = clsx(styles.button, passedClassName);
-      return <div className={className}>Click me</button>;
-    };
-    ```
-
-  - Use `theme` prop to override multiple styles inside a component
-
-    ```jsx
-    // signup_button.js
-    import buttonStyles from "signup_button.module.scss"
-
-    <Button theme={buttonStyles} />
-    ```
-
-    ```jsx
-    // button.js
-    import styles from "button.module.scss"
-
-    const Button = ({ theme }) => {
-      const className = clsx(styles.button, theme.button);
-      const iconClassName = clsx(styles.icon, theme.icon);
-      return (
-        <div className={className}>
-          Click me
-          <span className={iconClassName}>icon</span>
-        </button>
-      );
-    };
-    ```
-
-  - If you need to pass custom style names make sure they are mapped outside of the Component render call. That way the object remains the same between renders.
-
-    ```jsx
-    const Button = () => {
-      // bad
-      const theme = { ... };
-      return <Button theme={buttonStyles} />;
-    }
-    ```
-
-    ```jsx
-    // good
-    const theme = { ... };
-
-    const Button = () => {
-      return <Button theme={buttonStyles} />;
-    }
-    ```