propTypeHandler: Improve support for detecting composition from code

[fkling]

Imagine you have a component A that composes component B and therefore also accepts the same props as B. For example:

var A = React.createClass({
  propTypes: ...,
  render: {
      return <B {...this.props} />
  }
});

react-docgen is actually able to identify this composition if you merge B's propTypes into A:

propTypes: {
  ...B.propTypes,
  // more of A's propTypes here
}

But this is not only useful to make react-docgen happy, it's actually a better description of A's API. react-docgen will try to resolve B to its module path and add that to the composes field, e.g.

{
  description: '...',
  props: {...},
  composes: ['path/to/B']
}

Note that while parsing A, react-docgen will not parse B. It is up to you to pass B to react-docgen, or process that file in any way necessary. That means react-docgen doesn't actually care what B is, which brings me to my first point.

---

Relax the constraints for the spread operator in propTypes

Right now, react-docgen will only consider composition if the expression used is of form X.propTypes, i.e. it has to be a member expression which access propTypes. While this is fine for most cases, it obviously closes the door for modules which don't expose a propTypes property.

For example, consider you have a module that just defines prop types which are used by multiple components:

// SharedPropTypes.js
module.exports = {
  foo: React.PropTypes.number
};

// A.js
var SharedPropTypes = require('./SharedPropTypes');
var A = React.createClass({
  propTypes: {
    ...SharedPropTypes
  }
});

// B.js
// similar to A.js

Of course you can argue that no composition is taking place here, but we still want to be able to get a complete description of A's and B's API. And given the fact that react-docgen actually doesn't care what the SharedPropTypes module is, there is not really a reason to restrict it to that cases.

---

Support for API subsets

If you are composing components then the "parent" component might not actually support all the props of the composed component. It may only support a subset and set some props itself. For example:

var A = React.createClass({
  propTypes: ...,
  render: {
    return <B foo={this.props.foo}, bar={42} />
  }
});

So, instead of merging the complete propTypes object B all you need is B.propTypes.foo (you could easily do foo: B.propTypes.foo in this particular case, but please bear with me and imagine you have more than one prop (react-docgen would also not be possible to understand that it refers to module B, but I don't have a good solution for that yet)).

Destructuring actually gives us a nice statically analyzable way to specify this:

var {props, to, include} = B.propTypes;
var A = React.createClass({
  propTypes: {
    props,
    to,
    include,
    // A's props
  }
});

We could easily analyze that props, to, include comes from the module B originates from and create an entry in documentation object of the form:

{
  description: '...',
  props: {...},
  composes: [{module: 'path/to/B', include: ['props', 'to', 'include']}]
}

Again, it's up to you how to process this information, but at least you have it.

This would also work for excluding props:

var {do, not, include, ...propTypes} = B.propTypes;
var A = React.createClass({
  propTypes: {
    ...propTypes,
    // A's props
  }
});

We could easily analyze that props, to, include comes from the module B originates from and create an entry in documentation object of the form:

{
  description: '...',
  props: {...},
  composes: [{module: 'path/to/B', include: [], exclude: ['do', 'not', 'include']}]
}

Obviously this is only going to be useful if a flat structure is exported from the included module. I don't have a good idea for nested structures yet, but I'm also not sure if (default) support is necessary (or even possible (there is only so much you can statically analyze)). I'd rather encourage devs to keep things simple.

[fkling]

The relaxation was implemented in v1.1.0.