From f8f2c65e386f3c0665650c11b661dd710f117294 Mon Sep 17 00:00:00 2001
From: Alexander Fedyashov <alexander.mcgarret@gmail.com>
Date: Wed, 27 Sep 2017 10:49:52 +0300
Subject: [PATCH] docs(README): add motivation part to README.md (#17)

---
 README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 90 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 30524e6..1bce27d 100644
--- a/README.md
+++ b/README.md
@@ -6,30 +6,106 @@ Generates handledProps from defaultProps and propTypes during the build :sparkle
 [![Gemnasium](https://img.shields.io/gemnasium/layershifter/babel-plugin-transform-react-handled-props.svg?style=flat)](https://gemnasium.com/layershifter/babel-plugin-transform-react-handled-props)
 [![npm](https://img.shields.io/npm/v/babel-plugin-transform-react-handled-props.svg?style=flat)](https://www.npmjs.com/package/babel-plugin-transform-react-handled-props)
 
+## Installation
+
+```sh
+$ npm install --save-dev babel-plugin-transform-react-handled-props
+```
+
 ## Story
 
 This plugin was originally created for [Semantic React](https://github.com/Semantic-Org/Semantic-UI-React) package.
 It implements useful pattern with handled props by component, using it you can let down unhandled props to child component.
 
-## Installation
+## Motivation
 
-```sh
-$ npm install --save-dev babel-plugin-transform-react-handled-props
+Let's take an example from real life. There are cases when you need to pass some of the props to the child component.
+The simplest way is to use the destruction of the object.
+
+```jsx
+const Foo = (props) => {
+  const { className, ...rest } = props
+  const classes = classNames(className, 'foo')
+
+  return <div {...rest} className={classes} />
+}
+```
+
+The solution is simple and straightforward, but what if the props that will need to be handled is not used in the method?
+We still need to specify it explicitly.
+
+```jsx
+class Foo extends React.Component {
+  handleClick = (e) => this.props.onClick(e)
+
+  render() {
+    const { className, onClick, ...rest } = this.props
+    const classes = classNames(className, 'foo')
+
+    return <div {...rest} className={classes} onClick={this.handleClick} />
+  }
+}
 ```
 
-## Example
+And what if there are a lot of components? Yes, we will come to another solution, it's to rely on the React's `propTypes`.
+It's a good and logical solution.
+
+```jsx
+class Foo extends React.Component {
+  static propTypes = {
+    className: PropTypes.string,
+    onClick: PropTypes.func,
+  }
+
+  handleClick = (e) => this.props.onClick(e)
+
+  render() {
+    const { className } = this.props
+    const classes = classNames(className, 'foo')
+    const rest = _.omit(this.props, _.keys(Foo.propTypes))
+
+    return <div {...rest} className={classes} onClick={this.handleClick} />
+  }
+}
+```
+
+Looks pretty good? But, there is only one problem, we don't need `propTypes` in the production build.
+We can take the [plugin](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types) to remove them, but then our solution will be broken?
+It's possible that you already use this approach, but you can't get rid of `propTypes` in the your bundle.
+This plugin solves the described problem, so you can rely on `propTypes` and at the same time remove them from the production build.
+
+```jsx
+class Foo extends React.Component {
+  static propTypes = {
+    className: PropTypes.string,
+    onClick: PropTypes.func,
+  }
+
+  handleClick = (e) => this.props.onClick(e)
+
+  render() {
+    const { className } = this.props
+    const classes = classNames(className, 'foo')
+    const rest = _.omit(this.props, Foo.handledProps)
+
+    return <div {...rest} className={classes} onClick={this.handleClick} />
+  }
+}
+```
+
+## Example transform
 
 **In**
 
 ```js
 const Baz = (props) => (
   <div {...props} />
-);
+)
 
 Baz.propTypes = {
-  children: React.PropTypes.node,
-  className: React.PropTypes.string
-};
+  children: PropTypes.node,
+  className: PropTypes.string,
+}
 ```
 
 **Out**
@@ -37,14 +113,14 @@ Baz.propTypes = {
 ```js
 const Baz = (props) => (
   <div {...props} />
-);
+)
 
 Baz.handledProps = ['className'];
 
 Baz.propTypes = {
-  children: React.PropTypes.node,
-  className: React.PropTypes.string
-};
+  children: PropTypes.node,
+  className: PropTypes.string,
+}
 ```
 
 ## Usage
@@ -79,14 +155,14 @@ Absolutely :sunglasses: You can also use in production with [babel-plugin-transf
 
 ```js
 const Baz = (props) => {
-  const rest = _.omit(props, Baz.handledProps);
+  const rest = _.omit(props, Baz.handledProps)
 
   return (
     <div {...props}>
       <Foo {...rest} />
     </div>
   )
-};
+}
 ```
 
 ## License