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.