Skip to content

Commit

Permalink
Merge branch 'master' into hoc
Browse files Browse the repository at this point in the history
  • Loading branch information
danez committed Oct 16, 2019
2 parents 78cea9f + a1f9b9a commit f7f7376
Show file tree
Hide file tree
Showing 137 changed files with 6,767 additions and 3,278 deletions.
6 changes: 3 additions & 3 deletions .babelrc
Expand Up @@ -4,14 +4,14 @@
"@babel/preset-env",
{
"targets": {
"node": 6
}
"node": "8.10.0"
},
"shippedProposals": true
}
],
"@babel/preset-flow"
],
"plugins": [
"@babel/plugin-proposal-object-rest-spread",
"@babel/plugin-transform-runtime"
]
}
6 changes: 5 additions & 1 deletion .eslintrc.js
Expand Up @@ -16,7 +16,7 @@ module.exports = {
globals: {
ASTNode: true,
NodePath: true,
Recast: true,
$Exact: true,
},
overrides: [
{
Expand All @@ -27,5 +27,9 @@ module.exports = {
'no-unused-vars': 'off',
},
},
{
files: '@(src|bin)/**/__tests__/*-test.js',
env: { jest: true },
},
],
};
5 changes: 2 additions & 3 deletions .travis.yml
@@ -1,9 +1,8 @@
language: node_js
node_js:
- "11"
- "12"
- "10"
- "8"
- "6"
cache:
yarn: true
directories:
Expand All @@ -22,4 +21,4 @@ deploy:
local_dir: website/dist
on:
branch: master
node: "10"
node: "12"
36 changes: 25 additions & 11 deletions README.md
Expand Up @@ -2,7 +2,7 @@

`react-docgen` is a CLI and toolbox to help extracting information from [React][] components, and generate documentation from it.

It uses [recast][] and [@babel/parser][] to parse the source into an AST and provides methods to process this AST to extract the desired information. The output / return value is a JSON blob / JavaScript object.
It uses [ast-types][] and [@babel/parser][] to parse the source into an AST and provides methods to process this AST to extract the desired information. The output / return value is a JSON blob / JavaScript object.

It provides a default implementation for React components defined via
`React.createClass`, [ES2015 class definitions][classes] or functions
Expand Down Expand Up @@ -79,12 +79,23 @@ As with the CLI, this will look for the exported component created through `Reac

### parse(source \[, resolver \[, handlers \[, options\]\]\])

| Parameter | Type | Description |
| -------------- | ------ | --------------- |
| source | string | The source text |
| resolver | function | A function of the form `(ast: ASTNode, recast: Object) => (NodePath|Array<NodePath>)`. Given an AST and a reference to recast, it returns an (array of) NodePath which represents the component definition. |
| handlers | Array\<function\> | An array of functions of the form `(documentation: Documentation, definition: NodePath) => void`. Each function is called with a `Documentation` object and a reference to the component definition as returned by `resolver`. Handlers extract relevant information from the definition and augment `documentation`. |
| opt
#### source

Type: `string | Buffer`

The source text that react-docgen will try to extract the documentation from.

#### resolver

Type: `(ast: ASTNode, parser: { parse: (string) => ASTNode }) => (NodePath | Array<NodePath>)`

Given an AST and a reference to the parser, it returns an (array of) NodePath which represents the component definition.

#### handlers

Type: `Array<(documentation: Documentation, definition: NodePath, parser: { parse: (string) => ASTNode }) => void>`

Each function is called with a `Documentation` object, a reference to the component definition as returned by a `resolver` and a reference to the parser. Handlers extract relevant information from the definition and augment `documentation`.

#### options

Expand Down Expand Up @@ -239,15 +250,15 @@ we are getting this output:
}
```

## Flow Type support
## Flow and TypeScript support

If you are using [flow][flow] then react-docgen can also extract the flow type annotations. As flow has a way more advanced and fine granular type system, the returned types from react-docgen are different in comparison when using `React.PropTypes`.
If you are using [flow][flow] or [typescript][typescript] then react-docgen can also extract the type annotations. As flow and typescript have way more advanced and fine granular type systems, the returned types from react-docgen are different in comparison when using `React.PropTypes`.

> **Note**: react-docgen will not be able to grab the type definition if the type is imported or declared in a different file.
### Example

For the following component
For the following component with Flow types

```js
import React, { Component } from 'react';
Expand Down Expand Up @@ -387,6 +398,7 @@ The structure of the JSON blob / JavaScript object is as follows:
["raw": string]
},
"flowType": <flowType>,
"tsType": <tsType>,
"required": boolean,
"description": string,
["defaultValue": {
Expand All @@ -406,9 +418,11 @@ The structure of the JSON blob / JavaScript object is as follows:
- `<typeName>`: The name of the type, which is usually corresponds to the function name in `React.PropTypes`. However, for types define with `oneOf`, we use `"enum"` and for `oneOfType` we use `"union"`. If a custom function is provided or the type cannot be resolved to anything of `React.PropTypes`, we use `"custom"`.
- `<typeValue>`: Some types accept parameters which define the type in more detail (such as `arrayOf`, `instanceOf`, `oneOf`, etc). Those are stored in `<typeValue>`. The data type of `<typeValue>` depends on the type definition.
- `<flowType>`: If using flow type this property contains the parsed flow type as can be seen in the table above.
- `<tsType>`: If using TypeScript type this property contains the parsed TypeScript type as can be seen in the table above.

[react]: http://facebook.github.io/react/
[flow]: http://flowtype.org/
[recast]: https://github.com/benjamn/recast
[typescript]: http://typescriptlang.org/
[ast-types]: https://github.com/benjamn/ast-types
[@babel/parser]: https://github.com/babel/babel/tree/master/packages/babel-parser
[classes]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
249 changes: 249 additions & 0 deletions benchmark/fixtures/CircularProgress.js
@@ -0,0 +1,249 @@
import React from 'react';
import PropTypes from 'prop-types';
import clsx from 'clsx';
import { chainPropTypes } from '@material-ui/utils';
import withStyles from '../styles/withStyles';
import { capitalize } from '../utils/helpers';

const SIZE = 44;

function getRelativeValue(value, min, max) {
const clampedValue = Math.min(Math.max(min, value), max);
return (clampedValue - min) / (max - min);
}

function easeOut(t) {
t = getRelativeValue(t, 0, 1);
// https://gist.github.com/gre/1650294
t = (t -= 1) * t * t + 1;
return t;
}

function easeIn(t) {
return t * t;
}

export const styles = theme => ({
/* Styles applied to the root element. */
root: {
display: 'inline-block',
lineHeight: 1, // Keep the progress centered
},
/* Styles applied to the root element if `variant="static"`. */
static: {
transition: theme.transitions.create('transform'),
},
/* Styles applied to the root element if `variant="indeterminate"`. */
indeterminate: {
animation: 'mui-progress-circular-rotate 1.4s linear infinite',
// Backward compatible logic between JSS v9 and v10.
// To remove with the release of Material-UI v4
animationName: '$mui-progress-circular-rotate',
},
/* Styles applied to the root element if `color="primary"`. */
colorPrimary: {
color: theme.palette.primary.main,
},
/* Styles applied to the root element if `color="secondary"`. */
colorSecondary: {
color: theme.palette.secondary.main,
},
/* Styles applied to the `svg` element. */
svg: {},
/* Styles applied to the `circle` svg path. */
circle: {
stroke: 'currentColor',
// Use butt to follow the specification, by chance, it's already the default CSS value.
// strokeLinecap: 'butt',
},
/* Styles applied to the `circle` svg path if `variant="static"`. */
circleStatic: {
transition: theme.transitions.create('stroke-dashoffset'),
},
/* Styles applied to the `circle` svg path if `variant="indeterminate"`. */
circleIndeterminate: {
animation: 'mui-progress-circular-dash 1.4s ease-in-out infinite',
// Backward compatible logic between JSS v9 and v10.
// To remove with the release of Material-UI v4
animationName: '$mui-progress-circular-dash',
// Some default value that looks fine waiting for the animation to kicks in.
strokeDasharray: '80px, 200px',
strokeDashoffset: '0px', // Add the unit to fix a Edge 16 and below bug.
},
'@keyframes mui-progress-circular-rotate': {
'100%': {
transform: 'rotate(360deg)',
},
},
'@keyframes mui-progress-circular-dash': {
'0%': {
strokeDasharray: '1px, 200px',
strokeDashoffset: '0px',
},
'50%': {
strokeDasharray: '100px, 200px',
strokeDashoffset: '-15px',
},
'100%': {
strokeDasharray: '100px, 200px',
strokeDashoffset: '-125px',
},
},
/* Styles applied to the `circle` svg path if `disableShrink={true}`. */
circleDisableShrink: {
animation: 'none',
},
});

/**
* ## ARIA
*
* If the progress bar is describing the loading progress of a particular region of a page,
* you should use `aria-describedby` to point to the progress bar, and set the `aria-busy`
* attribute to `true` on that region until it has finished loading.
*/
const CircularProgress = React.forwardRef(function CircularProgress(
props,
ref,
) {
const {
classes,
className,
color,
disableShrink,
size,
style,
thickness,
value,
variant,
...other
} = props;

const circleStyle = {};
const rootStyle = {};
const rootProps = {};

if (variant === 'determinate' || variant === 'static') {
const circumference = 2 * Math.PI * ((SIZE - thickness) / 2);
circleStyle.strokeDasharray = circumference.toFixed(3);
rootProps['aria-valuenow'] = Math.round(value);

if (variant === 'static') {
circleStyle.strokeDashoffset = `${(
((100 - value) / 100) *
circumference
).toFixed(3)}px`;
rootStyle.transform = 'rotate(-90deg)';
} else {
circleStyle.strokeDashoffset = `${(
easeIn((100 - value) / 100) * circumference
).toFixed(3)}px`;
rootStyle.transform = `rotate(${(easeOut(value / 70) * 270).toFixed(
3,
)}deg)`;
}
}

return (
<div
className={clsx(
classes.root,
{
[classes[`color${capitalize(color)}`]]: color !== 'inherit',
[classes.indeterminate]: variant === 'indeterminate',
[classes.static]: variant === 'static',
},
className,
)}
style={{ width: size, height: size, ...rootStyle, ...style }}
ref={ref}
role="progressbar"
{...rootProps}
{...other}
>
<svg
className={classes.svg}
viewBox={`${SIZE / 2} ${SIZE / 2} ${SIZE} ${SIZE}`}
>
<circle
className={clsx(classes.circle, {
[classes.circleIndeterminate]: variant === 'indeterminate',
[classes.circleStatic]: variant === 'static',
[classes.circleDisableShrink]: disableShrink,
})}
style={circleStyle}
cx={SIZE}
cy={SIZE}
r={(SIZE - thickness) / 2}
fill="none"
strokeWidth={thickness}
/>
</svg>
</div>
);
});

CircularProgress.propTypes = {
/**
* Override or extend the styles applied to the component.
* See [CSS API](#css) below for more details.
*/
classes: PropTypes.object.isRequired,
/**
* @ignore
*/
className: PropTypes.string,
/**
* The color of the component. It supports those theme colors that make sense for this component.
*/
color: PropTypes.oneOf(['primary', 'secondary', 'inherit']),
/**
* If `true`, the shrink animation is disabled.
* This only works if variant is `indeterminate`.
*/
disableShrink: chainPropTypes(PropTypes.bool, props => {
if (props.disableShrink && props.variant !== 'indeterminate') {
return new Error(
'Material-UI: you have provided the `disableShrink` property ' +
'with a variant other than `indeterminate`. This will have no effect.',
);
}

return null;
}),
/**
* The size of the circle.
*/
size: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
/**
* @ignore
*/
style: PropTypes.object,
/**
* The thickness of the circle.
*/
thickness: PropTypes.number,
/**
* The value of the progress indicator for the determinate and static variants.
* Value between 0 and 100.
*/
value: PropTypes.number,
/**
* The variant to use.
* Use indeterminate when there is no progress value.
*/
variant: PropTypes.oneOf(['determinate', 'indeterminate', 'static']),
};

CircularProgress.defaultProps = {
color: 'primary',
disableShrink: false,
size: 40,
thickness: 3.6,
value: 0,
variant: 'indeterminate',
};

export default withStyles(styles, { name: 'MuiCircularProgress', flip: false })(
CircularProgress,
);

0 comments on commit f7f7376

Please sign in to comment.