Addon-docs: Snapshot testing and bug reporting for props tables

.eslintrc.js

@@ -41,6 +41,7 @@ module.exports = {
     {
       files: [
         '**/__tests__/**',
+        '**/__testfixtures__/**',
         '**/*.test.*',
         '**/*.stories.*',
         '**/storyshots/**/stories/**',

addons/docs/docs/props-tables.md

@@ -0,0 +1,97 @@
+<center>
+  <img src="./media/props-tables-hero.png" width="100%" />
+</center>
+
+<h1>Storybook Docs Props Tables</h1>
+
+Storybook Docs automatically generates props tables for components in supported frameworks. This document is a consolidated summary of prop tables, provides instructions for reporting bugs, and list known limitations for each framework.
+
+- [Usage](#usage)
+- [Reporting a bug](#reporting-a-bug)
+- [Known limitations](#known-limitations)
+  - [React](#react)
+  - [Vue](#vue)
+  - [Angular](#angular)
+  - [Web components](#web-components)
+  - [Ember](#ember)
+- [More resources](#more-resources)
+
+## Usage
+
+For framework-specific setup instructions, see the framework's README: [React](../../react/README.md), [Vue](../../vue/README.md), [Angular](../../angular/README.md), [Web Components](../../web-components/README.md), [Ember](../../ember/README.md).
+
+To use the props table in [DocsPage](./docspage.md), simply export a component property on your stories metadata:
+
+```js
+// MyComponent.stories.js
+import { MyComponent } from './MyComponent';
+
+export default {
+  title: 'MyComponent',
+  component: MyComponent,
+};
+// stories etc...
+```
+
+To use the props table in [MDX](./mdx.md), use the `Props` block:
+
+```js
+// MyComponent.stories.mdx
+import { Props } from '@storybook/addon-docs/blocks';
+import { MyComponent } from './MyComponent';
+
+# My Component!
+
+<Props of={MyComponent} />
+```
+
+## Reporting a bug
+
+Extracting component properties from source is a tricky problem with thousands of corner cases. We've designed this package and its tests to accurately isolate problems, since the cause could either be in this package or (likely) one of the packages it depends on.
+
+If you're seeing a problem with your prop table, here's what to do.
+
+First, look to see if there's already a test case that corresponds to your situation. If there is, it should be documented in the [Known Limitations](#known-limitations) section above. There should also be one or more corresponding test fixtures contained in this package. For example, if you are using React, look under the directory `./src/frameworks/react/__testfixtures__`.
+
+If your problem is not already represented here, do the following:
+
+1. Create a **MINIMAL** repro for your problem. Each case should be just a few lines of code.
+2. Place it in the appropriate directory `./src/<framework>/__testfixtures__/`, e.g. `./src/react/__testfixtures__/XXXX-some-description`, where `XXXX` is the corresponding github issue.
+3. Run the tests for your `<framework>`, e.g. `yarn jest --testPathPattern=react-properties.test.ts --watch`
+4. Inspect the output files for your test case.
+5. Add the example to the appropriate stories file, e.g. `react-properties.stories.ts` for `react`, for a visual repro
+
+If the problem appears to be an issue with this library, file an issue and include a PR that includes your repro.
+
+If the problem appears to be an issue with the sub-package, please file an issue on the appropriate sub-package, document the limitation in [Known Limitations](#known-limitations) below, link to that issue, and submit a PR including the updated documentation and fixtures/snapshots.
+
+## Known limitations
+
+This package relies on a variety of sub-packages to extract property information from components. Many of the bugs in this package correspond to bugs in a sub-package. Since we don't maintain the sub-packages, the best we can do for now is (1) document these limitations, (2) provide clean reproductions to the sub-package, (3) optionally provide PRs to those packages to fix the problems.
+
+### React
+
+SB Docs for React uses `babel-plugin-react-docgen`/`react-docgen` for both JS PropTypes prop tables and, as of 6.0, TypeScript-driven props tables.
+
+### Vue
+
+SB Docs for Vue uses `vue-docgen-loader`/`vue-docgen-api` for SFC and JSX components.
+
+### Angular
+
+SB Docs for Angular uses `compodoc` for prop table information.
+
+### Web components
+
+SB Docs for Web-components uses `custom-elements.json` for prop table information.
+
+### Ember
+
+SB Docs for Ember uses `yui-doc` for prop table information.
+
+## More resources
+
+- References: [README](../README.md) / [DocsPage](docspage.md) / [MDX](mdx.md) / [FAQ](faq.md) / [Recipes](recipes.md) / [Theming](theming.md)
+- Framework-specific docs: [React](../react/README.md) / [Vue](../vue/README.md) / [Angular](../angular/README.md) / [Web components](../web-components/README.md) / [Ember](../ember/README.md)
+- Announcements: [Vision](https://medium.com/storybookjs/storybook-docs-sneak-peak-5be78445094a) / [DocsPage](https://medium.com/storybookjs/storybook-docspage-e185bc3622bf) / [MDX](https://medium.com/storybookjs/rich-docs-with-storybook-mdx-61bc145ae7bc) / [Framework support](https://medium.com/storybookjs/storybook-docs-for-new-frameworks-b1f6090ee0ea)
+- Example: [Storybook Design System](https://github.com/storybookjs/design-system)

addons/docs/package.json

@@ -69,16 +69,18 @@
     "remark-slug": "^5.1.2",
     "ts-dedent": "^1.1.1",
     "util-deprecate": "^1.0.2",
-    "vue-docgen-api": "^4.1.0",
-    "vue-docgen-loader": "^1.3.0-beta.0"
+    "vue-docgen-api": "^4.7.0",
+    "vue-docgen-loader": "^1.4.0"
   },
   "devDependencies": {
     "@types/doctrine": "^0.0.3",
     "@types/enzyme": "^3.10.3",
     "@types/jest": "^25.1.1",
     "@types/prop-types": "^15.5.9",
     "@types/util-deprecate": "^1.0.0",
-    "jest-specific-snapshot": "^2.0.0"
+    "babel-plugin-react-docgen": "^4.1.0",
+    "jest-specific-snapshot": "^2.0.0",
+    "require-from-string": "^2.0.2"
   },
   "peerDependencies": {
     "@babel/core": "^7.0.0-0",

addons/docs/src/frameworks/react/__testfixtures__/js-class-component/docgen.snapshot

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`react component properties js-class-component 1`] = `
+"/* eslint-disable react/prefer-stateless-function */
+import React from 'react';
+import PropTypes from 'prop-types';
+/**
+ * Component description
+ */
+
+class ErrorBox extends React.Component {
+  render() {
+    const {
+      children
+    } = this.props;
+    return React.createElement(\\"div\\", {
+      className: \\"error-box\\"
+    }, children);
+  }
+
+}
+
+ErrorBox.propTypes = {
+  /**
+   * PropTypes description
+   */
+  children: PropTypes.node.isRequired
+};
+ErrorBox.__docgenInfo = {
+  \\"description\\": \\"Component description\\",
+  \\"methods\\": [],
+  \\"displayName\\": \\"ErrorBox\\",
+  \\"props\\": {
+    \\"children\\": {
+      \\"type\\": {
+        \\"name\\": \\"node\\"
+      },
+      \\"required\\": true,
+      \\"description\\": \\"PropTypes description\\"
+    }
+  }
+};
+export default ErrorBox;
+export const component = ErrorBox;"
+`;

addons/docs/src/frameworks/react/__testfixtures__/js-class-component/input.js

@@ -0,0 +1,24 @@
+/* eslint-disable react/prefer-stateless-function */
+import React from 'react';
+import PropTypes from 'prop-types';
+
+/**
+ * Component description
+ */
+class ErrorBox extends React.Component {
+  render() {
+    const { children } = this.props;
+
+    return <div className="error-box">{children}</div>;
+  }
+}
+
+ErrorBox.propTypes = {
+  /**
+   * PropTypes description
+   */
+  children: PropTypes.node.isRequired,
+};
+
+export default ErrorBox;
+export const component = ErrorBox;

addons/docs/src/frameworks/react/__testfixtures__/js-class-component/properties.snapshot

@@ -0,0 +1,18 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`react component properties js-class-component 1`] = `
+Object {
+  "rows": Array [
+    Object {
+      "defaultValue": null,
+      "description": "PropTypes description",
+      "name": "children",
+      "required": true,
+      "type": Object {
+        "detail": undefined,
+        "summary": "node",
+      },
+    },
+  ],
+}
+`;

addons/docs/src/frameworks/react/__testfixtures__/ts-function-component/docgen.snapshot

@@ -0,0 +1,64 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`react component properties ts-function-component 1`] = `
+"import React from 'react';
+
+/**
+ * The world's most _basic_ button
+ */
+export const Button = ({
+  onClick
+}) => React.createElement(\\"button\\", {
+  onClick: onClick,
+  type: \\"button\\"
+}, \\"hello\\");
+Button.defaultProps = {
+  primary: true,
+  secondary: false
+};
+export const component = Button;
+Button.__docgenInfo = {
+  \\"description\\": \\"The world's most _basic_ button\\",
+  \\"methods\\": [],
+  \\"displayName\\": \\"Button\\",
+  \\"props\\": {
+    \\"primary\\": {
+      \\"defaultValue\\": {
+        \\"value\\": \\"true\\",
+        \\"computed\\": false
+      },
+      \\"required\\": false,
+      \\"tsType\\": {
+        \\"name\\": \\"boolean\\"
+      },
+      \\"description\\": \\"Is primary?\\"
+    },
+    \\"secondary\\": {
+      \\"defaultValue\\": {
+        \\"value\\": \\"false\\",
+        \\"computed\\": false
+      },
+      \\"required\\": false,
+      \\"tsType\\": {
+        \\"name\\": \\"boolean\\"
+      },
+      \\"description\\": \\"default is false\\"
+    },
+    \\"onClick\\": {
+      \\"required\\": false,
+      \\"tsType\\": {
+        \\"name\\": \\"signature\\",
+        \\"type\\": \\"function\\",
+        \\"raw\\": \\"() => void\\",
+        \\"signature\\": {
+          \\"arguments\\": [],
+          \\"return\\": {
+            \\"name\\": \\"void\\"
+          }
+        }
+      },
+      \\"description\\": \\"Simple click handler\\"
+    }
+  }
+};"
+`;

addons/docs/src/frameworks/react/__testfixtures__/ts-function-component/input.tsx

@@ -0,0 +1,34 @@
+import React, { FC } from 'react';
+
+interface ButtonProps {
+  /**
+   * Simple click handler
+   */
+  onClick?: () => void;
+
+  /**
+   * Is primary?
+   */
+  primary?: boolean;
+
+  /**
+   * default is false
+   */
+  secondary?: boolean;
+}
+
+/**
+ * The world's most _basic_ button
+ */
+export const Button: React.FC<ButtonProps> = ({ onClick }: ButtonProps) => (
+  <button onClick={onClick} type="button">
+    hello
+  </button>
+);
+
+Button.defaultProps = {
+  primary: true,
+  secondary: false,
+};
+
+export const component = Button;

addons/docs/src/frameworks/react/__testfixtures__/ts-function-component/properties.snapshot

@@ -0,0 +1,47 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`react component properties ts-function-component 1`] = `
+Object {
+  "rows": Array [
+    Object {
+      "defaultValue": Object {
+        "detail": undefined,
+        "summary": "true",
+      },
+      "description": "Is primary?",
+      "name": "primary",
+      "required": false,
+      "type": Object {
+        "detail": undefined,
+        "summary": "boolean",
+      },
+    },
+    Object {
+      "defaultValue": Object {
+        "detail": undefined,
+        "summary": "false",
+      },
+      "description": "default is false",
+      "name": "secondary",
+      "required": false,
+      "type": Object {
+        "detail": undefined,
+        "summary": "boolean",
+      },
+    },
+    Object {
+      "defaultValue": Object {
+        "detail": undefined,
+        "summary": "2",
+      },
+      "description": "Simple click handler",
+      "name": "onClick",
+      "required": false,
+      "type": Object {
+        "detail": undefined,
+        "summary": "signature",
+      },
+    },
+  ],
+}
+`;

addons/docs/src/frameworks/react/react-properties.stories.tsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import { storiesOf } from '@storybook/react';
+import { PropsTable } from '@storybook/components';
+import { extractProps } from './extractProps';
+
+const fixtures = ['js-class-component', 'ts-function-component'];
+
+const stories = storiesOf('Properties/React', module);
+
+fixtures.forEach(fixture => {
+  // eslint-disable-next-line import/no-dynamic-require, global-require
+  const { component } = require(`./__testfixtures__/${fixture}/input`);
+  const props = extractProps(component);
+  stories.add(fixture, () => <PropsTable {...props} />);
+});