add vue

Author: wojtek-krysiak

README.md

@@ -76,7 +76,7 @@ class YourClass {
 
 ## @component plugin [BETA]
 
-Better-docs also allows you to document your [React](https://reactjs.org/) ([Vue](https://vuejs.org/) coming soon) components automatically. The only thing you have to do is to add a `@component` tag. It will take all props from your components and along with an `@example` tag - will generate a __live preview__.
+Better-docs also allows you to document your [React](https://reactjs.org/) and [Vue](https://vuejs.org/) components automatically. The only thing you have to do is to add a `@component` tag. It will take all props from your components and along with an `@example` tag - will generate a __live preview__.
 
 ### Installation instructions
 
@@ -132,9 +132,36 @@ export default Documented
 
 The plugin will take the information from your [PropTypes](https://reactjs.org/docs/typechecking-with-proptypes.html) and put them into an array.
 
+For Vue it looks similar:
+
+```vue
+<script>
+/**
+ * @component
+ */
+export default {
+  name: 'ExampleComponent',
+  props: {
+    spent: {
+      type: Number,
+      default: 30,
+    },
+    remaining: {
+      type: Number,
+      default: 40,
+    }
+  },
+}
+</script>
+```
+
+Here props will be taken from `props` property.
+
 ### Preview
 
-`@component` plugin also modifies the behaviour of `@example` tag in a way that it can generate an actual __component preview__. What you have to do is to ad an `@example` tag and return component from it:
+`@component` plugin also modifies the behaviour of `@example` tag in a way that it can generate an actual __component preview__. What you have to do is to add an `@example` tag and return component from it:
+
+**React example:**
 
 ```javacript
 /**
@@ -152,7 +179,55 @@ const Documented = (props) => {
 }
 ```
 
-You can put as many `@example` tags as you like in one component.
+**Vue example 1:**
+
+```
+<script>
+/**
+ * @component
+ * @example
+ * <ExampleComponent :spent="100" :remaining="50"></ExampleComponent>
+ */
+export default {
+  name: 'ExampleComponent',
+  //...
+}
+</script>
+```
+
+**Vue example 2:**
+
+```
+<script>
+/**
+ * @component
+ * @example
+ * {
+ *   template: `<Box>
+ *     <ProgressBar :spent="spent" :remaining="50"></ProgressBar>
+ *     <ProgressBar :spent="50" :remaining="50" style="margin-top: 20px"></ProgressBar>
+ *   </Box>`,
+ *   data: function() {
+ *     return {spent: 223};
+ *   }
+ * }
+ */
+export default {
+  name: 'ExampleComponent',
+  //...
+}
+</script>
+```
+
+You can put as many `@example` tags as you like in one component and name each of them like this:
+
+```javascript
+/**
+ * @component
+ * @example <caption>Example usage of method1.</caption>
+ * // your example here
+ */
+```
 
 ### Mixing components in preview
 
@@ -182,7 +257,7 @@ const Component1 = (props) => {...}
 const Component2 = (props) => {...}
 ```
 
-### Wrapper components
+### Wrapper component [only React]
 
 Most probably your components will have to be run within a particular context, like within redux store provider or with custom CSS libraries.
 You can simulate this by passing a `component.wrapper` in your `jsdoc.json`:
@@ -233,7 +308,7 @@ const Component = (props) => {
 export default Component
 ```
 
-### Styling examples
+### Styling React examples
 
 Better-docs inserts all examples within an `iframe`. This results in following styling options:
 
@@ -277,7 +352,7 @@ export default Component
 
 `@component` plugin creates an entry file: `.entry.js` in your _docs_ output folder. Sometimes you might want to add something to it. You can do this by passing: `component.entry` option, which is an array of strings.
 
-So let's say you want to add `babel-polyfill` to your bundle. You can do it like this:
+So let's say you want to add `babel-polyfill` and 'bulma.css' framework to your bundle. You can do it like this:
 
 ```json
 // jsdoc.json
@@ -288,7 +363,8 @@ So let's say you want to add `babel-polyfill` to your bundle. You can do it like
             "name": "AdminBro Documentation",
             "component": {
                 "entry": [
-                    "import \"babel-polyfill\""
+                    "import 'babel-polyfill';",
+                    "import 'bulma/css/bulma.css';"
                 ]
             },
             "...": "...",
@@ -297,10 +373,6 @@ So let's say you want to add `babel-polyfill` to your bundle. You can do it like
 }
 ```
 
-### Document Vue components
-
-_Vue is coming soon_
-
 ## Customization
 
 First of all, let me state that better-docs extends the `default` template. That is why default template parameters are also handled.

bundler.js

@@ -36,6 +36,13 @@ module.exports = function bundle (Components, out, config) {
       window.Wrapper = Wrapper;\n
     `
   }
+
+  // Import css
+  init = init + `
+    import './styles/reset.css';\n
+    import './styles/iframe.css';\n
+  `
+
   if (config.betterDocs.component) {
     if(config.betterDocs.component.wrapper) {
       const absolute = path.resolve(config.betterDocs.component.wrapper)
@@ -49,12 +56,13 @@ module.exports = function bundle (Components, out, config) {
       init = `${config.betterDocs.component.entry.join('\n')}\n${init}`
     }
   }
+  
   const entryFile = init + Components.map(c => {
     const { displayName, filePath} = c.component
     const relativePath = path.relative(absoluteOut, filePath)
     return [
       `import ${displayName} from '${relativePath}';`,
-      `Components.${displayName} = ${displayName};`,
+      `Components['${displayName}'] = ${displayName};`,
     ].join('\n')
   }).join('\n\n')
 

component.js

@@ -55,8 +55,15 @@ var parseReact = function (filePath, doclet) {
   }
 
   return {
-    props: docGen.props,
-    methods: docGen.methods,
+    props: Object.entries(docGen.props || {}).map(([key, prop]) => ({
+      name: key,
+      description: prop.description,
+      type: prop.type.name,
+      required: typeof prop.required === 'boolean' && prop.required,
+      defaultValue: prop.defaultValue
+        ? (prop.defaultValue.computed ? 'function()' : prop.defaultValue.value)
+        : undefined
+    })),
     displayName: docGen.displayName,
     filePath: filePath,
   }
@@ -85,3 +92,4 @@ var parseVue = function (filePath, doclet) {
 }
 
 exports.parseVue = parseVue
+exports.parseReact = parseReact

component.spec.js

@@ -1,9 +1,10 @@
 const path = require('path')
 const { expect } = require('chai')
 
-const { parseVue } = require('./component')
+const { parseVue, parseReact } = require('./component')
 
 const VUE_PATH = path.join(__dirname, 'fixtures/component.vue')
+const REACT_PATH = path.join(__dirname, 'fixtures/component.jsx')
 
 describe('@component', function () {
   describe('.parseVue', function () {
@@ -36,4 +37,26 @@ describe('@component', function () {
       })
     })
   })
+
+  describe('.parseReact', function () {
+    beforeEach(function () {
+      this.doclet = {}
+      this.output = parseReact(REACT_PATH, this.doclet)
+    })
+
+    it('returns displayName', function () {
+      expect(this.output.displayName).to.equal('Documented')
+    })
+
+    it('returns prop types', function () {
+      expect(this.output.props).to.have.lengthOf(2)
+      expect(this.output.props[0]).to.deep.equal({
+        description: 'Text is a text',
+        name: 'text',
+        required: false,
+        type: 'string',
+        defaultValue: '\'Hello World\''
+      })
+    })
+  })
 })

fixtures/component.jsx

@@ -0,0 +1,55 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import styled from 'styled-components'
+
+const Bold = styled.div`
+  background: red;
+  color: #fff;
+  padding: 5px;
+`
+
+/**
+ * Some documented component
+ * 
+ * @component
+ * @example <caption>Default example</caption>
+ * const text = 'Meva'
+ * return (
+ *   <Documented2>
+ *     <Documented text={text} />
+ *   </Documented2>
+ * )
+ * 
+ * @example <caption>Ala ma kota</caption>
+ * const text = 'some example text 2'
+ * return (
+ *   <Documented2>
+ *     <Documented text={text} header={'sime'} />
+ *   </Documented2>
+ * )
+ */
+const Documented = (props) => {
+  const { text, header } = props
+  return (
+    <p>
+      {header}
+      <Bold>
+        {text}
+      </Bold>
+    </p>
+  )
+}
+
+Documented.propTypes = {
+  /**
+   * Text is a text
+   */
+  text: PropTypes.string,
+  header: PropTypes.string.isRequired,
+}
+
+Documented.defaultProps = {
+  text: 'Hello World',
+}
+
+export default Documented

lib/react-wrapper.js

@@ -61,11 +61,13 @@ function (_React$Component) {
     window.component = window.component || {};
     _this.iframeRef = _react["default"].createRef();
     _this.handleChange = _this.handleChange.bind(_assertThisInitialized(_this));
+    _this.toggleEditor = _this.toggleEditor.bind(_assertThisInitialized(_this));
     var example = props.example;
     example = example || 'return (<div>Example</div>)';
     _this.state = {
       example: example,
-      height: 200
+      height: 200,
+      showEditor: false
     };
 
     _this.executeScript(example);
@@ -118,7 +120,7 @@ function (_React$Component) {
     key: "computeHeight",
     value: function computeHeight() {
       var height = this.state.height;
-      var padding = 30; // buffer for any unstyled margins
+      var padding = 5; // buffer for any unstyled margins
 
       if (this.iframeRef.current && this.iframeRef.current.node.contentDocument && this.iframeRef.current.node.contentDocument.body.offsetHeight !== 0 && this.iframeRef.current.node.contentDocument.body.offsetHeight !== height - padding) {
         this.setState({
@@ -131,15 +133,47 @@ function (_React$Component) {
     value: function componentDidUpdate() {
       this.computeHeight();
     }
+  }, {
+    key: "toggleEditor",
+    value: function toggleEditor(event) {
+      event.preventDefault();
+      this.setState(function (state) {
+        return _objectSpread2({}, state, {
+          showEditor: !state.showEditor
+        });
+      });
+    }
   }, {
     key: "render",
     value: function render() {
       var _this2 = this;
 
       var _this$state = this.state,
           component = _this$state.component,
-          height = _this$state.height;
-      return _react["default"].createElement("div", null, _react["default"].createElement("div", null, _react["default"].createElement("div", {
+          height = _this$state.height,
+          showEditor = _this$state.showEditor;
+      return _react["default"].createElement("div", null, _react["default"].createElement(_reactFrameComponent["default"], {
+        className: "component-wrapper",
+        ref: this.iframeRef,
+        style: {
+          width: '100%',
+          height: height
+        },
+        onLoad: this.computeHeight()
+      }, _react["default"].createElement("link", {
+        type: "text/css",
+        rel: "stylesheet",
+        href: "./build/entry.css"
+      }), _react["default"].createElement(_reactFrameComponent.FrameContextConsumer, null, function (frameContext) {
+        return _react["default"].createElement(_componentRenderer["default"], {
+          frameContext: frameContext
+        }, component);
+      })), _react["default"].createElement("div", {
+        "class": "bd__button"
+      }, _react["default"].createElement("a", {
+        href: "#",
+        onClick: this.toggleEditor
+      }, "Modify Example Code")), showEditor ? _react["default"].createElement("div", {
         className: "field"
       }, _react["default"].createElement(_reactAce["default"], {
         style: {
@@ -157,23 +191,7 @@ function (_React$Component) {
         editorProps: {
           $useSoftTabs: true
         }
-      }))), _react["default"].createElement("div", null, _react["default"].createElement("h5", null, "Preview"), _react["default"].createElement(_reactFrameComponent["default"], {
-        className: "component-wrapper",
-        ref: this.iframeRef,
-        style: {
-          width: '100%',
-          height: height
-        },
-        onLoad: this.computeHeight()
-      }, _react["default"].createElement("link", {
-        type: "text/css",
-        rel: "stylesheet",
-        href: "./build/entry.css"
-      }), _react["default"].createElement(_reactFrameComponent.FrameContextConsumer, null, function (frameContext) {
-        return _react["default"].createElement(_componentRenderer["default"], {
-          frameContext: frameContext
-        }, component);
-      }))));
+      })) : "");
     }
   }]);