Addon-docs: Docgen lib maintenance

addons/docs/src/blocks/Description.tsx

@@ -2,7 +2,7 @@ import React, { FunctionComponent, useContext } from 'react';
 import { Description, DescriptionProps as PureDescriptionProps } from '@storybook/components';
 import { DocsContext, DocsContextProps } from './DocsContext';
 import { Component, CURRENT_SELECTION, DescriptionSlot } from './shared';
-import { str } from '../lib/docgen/utils';
+import { str } from '../lib/docgen';
 
 export enum DescriptionType {
   INFO = 'info',

addons/docs/src/frameworks/react/extractProps.ts

@@ -1,7 +1,7 @@
 import PropTypes from 'prop-types';
 import { isForwardRef, isMemo } from 'react-is';
 import { PropDef } from '@storybook/components';
-import { hasDocgen, extractPropsFromDocgen, PropsExtractor, TypeSystem } from '../../lib/docgen';
+import { hasDocgen, extractComponentProps, PropsExtractor, TypeSystem } from '../../lib/docgen';
 import { Component } from '../../blocks/shared';
 import { enhancePropTypesProps } from './propTypes/handleProp';
 
@@ -32,7 +32,7 @@ function getPropDefs(component: Component, section: string): PropDef[] {
     }
   }
 
-  const extractedProps = extractPropsFromDocgen(processedComponent, section);
+  const extractedProps = extractComponentProps(processedComponent, section);
   if (extractedProps.length === 0) {
     return [];
   }

addons/docs/src/frameworks/react/propTypes/handleProp.test.ts

@@ -3,7 +3,7 @@
 import { PropDef } from '@storybook/components';
 import PropTypes from 'prop-types';
 import { Component } from '../../../blocks/shared';
-import { extractPropsFromDocgen, DocgenInfo } from '../../../lib/docgen';
+import { extractComponentProps, DocgenInfo } from '../../../lib/docgen';
 import { enhancePropTypesProp, enhancePropTypesProps } from './handleProp';
 
 const DOCGEN_SECTION = 'props';
@@ -43,7 +43,7 @@ function createComponent({ propTypes = {}, defaultProps = {}, docgenInfo = {} })
 }
 
 function extractPropDef(component: Component): PropDef {
-  return enhancePropTypesProp(extractPropsFromDocgen(component, DOCGEN_SECTION)[0]);
+  return enhancePropTypesProp(extractComponentProps(component, DOCGEN_SECTION)[0]);
 }
 
 describe('enhancePropTypesProp', () => {
@@ -914,7 +914,7 @@ describe('enhancePropTypesProps', () => {
     });
 
     const props = enhancePropTypesProps(
-      extractPropsFromDocgen(component, DOCGEN_SECTION),
+      extractComponentProps(component, DOCGEN_SECTION),
       component
     );
 
@@ -945,7 +945,7 @@ describe('enhancePropTypesProps', () => {
     });
 
     const props = enhancePropTypesProps(
-      extractPropsFromDocgen(component, DOCGEN_SECTION),
+      extractComponentProps(component, DOCGEN_SECTION),
       component
     );
 

addons/docs/src/frameworks/vue/config.tsx

@@ -4,7 +4,7 @@ import toReact from '@egoist/vue-to-react';
 import { StoryFn } from '@storybook/addons';
 import { addParameters } from '@storybook/client-api';
 import { extractProps } from './extractProps';
-import { extractComponentDescription } from '../../lib/docgen/utils';
+import { extractComponentDescription } from '../../lib/docgen';
 
 addParameters({
   docs: {

addons/docs/src/frameworks/vue/extractProps.ts

@@ -1,5 +1,5 @@
 import { PropDef } from '@storybook/components';
-import { PropsExtractor, hasDocgen, extractPropsFromDocgen } from '../../lib/docgen';
+import { PropsExtractor, hasDocgen, extractComponentProps } from '../../lib/docgen';
 
 const SECTIONS = ['props', 'events', 'slots'];
 
@@ -9,7 +9,7 @@ export const extractProps: PropsExtractor = component => {
   }
   const sections: Record<string, PropDef[]> = {};
   SECTIONS.forEach(section => {
-    sections[section] = extractPropsFromDocgen(component, section).map(x => x.propDef);
+    sections[section] = extractComponentProps(component, section).map(x => x.propDef);
   });
   return { sections };
 };

addons/docs/src/lib/docgen/createPropDef.ts

@@ -1,17 +1,29 @@
 import { isNil } from 'lodash';
-import { PropDef } from '@storybook/components';
-import { TypeSystem, DocgenInfo, DocgenType } from './types';
+import { PropDef, PropDefaultValue } from '@storybook/components';
+import { TypeSystem, DocgenInfo, DocgenType, DocgenPropDefaultValue } from './types';
 import { JsDocParsingResult } from '../jsdocParser';
-import { createDefaultValue } from './createDefaultValue';
 import { createSummaryValue } from '../utils';
 import { createFlowPropDef } from './flow/createPropDef';
+import { isDefaultValueBlacklisted } from './utils/defaultValue';
 
 export type PropDefFactory = (
   propName: string,
   docgenInfo: DocgenInfo,
   jsDocParsingResult?: JsDocParsingResult
 ) => PropDef;
 
+function createDefaultValue(defaultValue: DocgenPropDefaultValue): PropDefaultValue {
+  if (!isNil(defaultValue)) {
+    const { value } = defaultValue;
+
+    if (!isDefaultValueBlacklisted(value)) {
+      return createSummaryValue(value);
+    }
+  }
+
+  return null;
+}
+
 function createBasicPropDef(name: string, type: DocgenType, docgenInfo: DocgenInfo): PropDef {
   const { description, required, defaultValue } = docgenInfo;
 

addons/docs/src/lib/docgen/extractDocgenProps.test.ts

@@ -1,7 +1,7 @@
 /* eslint-disable no-underscore-dangle */
 
 import { Component } from '../../blocks/shared';
-import { extractPropsFromDocgen } from './extractDocgenProps';
+import { extractComponentProps } from './extractDocgenProps';
 
 const DOCGEN_SECTION = 'props';
 const PROP_NAME = 'propName';
@@ -54,103 +54,127 @@ function createComponent(docgenInfo: Record<string, any>): Component {
 }
 
 TypeSystems.forEach(x => {
-  it('should map defaults docgen info properly', () => {
-    const component = createComponent({
-      ...createStringType(x),
-      description: 'Hey! Hey!',
-      defaultValue: {
-        value: 'Default',
-      },
+  describe(`${x.name}`, () => {
+    it('should map defaults docgen info properly', () => {
+      const component = createComponent({
+        ...createStringType(x),
+        description: 'Hey! Hey!',
+        defaultValue: {
+          value: 'Default',
+        },
+      });
+
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
+
+      expect(propDef.name).toBe(PROP_NAME);
+      expect(propDef.type.summary).toBe('string');
+      expect(propDef.description).toBe('Hey! Hey!');
+      expect(propDef.required).toBe(false);
+      expect(propDef.defaultValue.summary).toBe('Default');
     });
 
-    const { propDef } = extractPropsFromDocgen(component, DOCGEN_SECTION)[0];
+    it('should remove JSDoc tags from the description', () => {
+      const component = createComponent({
+        ...createStringType(x),
+        description: 'Hey!\n@param event\nreturns {string}',
+      });
 
-    expect(propDef.name).toBe(PROP_NAME);
-    expect(propDef.type.summary).toBe('string');
-    expect(propDef.description).toBe('Hey! Hey!');
-    expect(propDef.required).toBe(false);
-    expect(propDef.defaultValue.summary).toBe('Default');
-  });
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
 
-  it('should remove JSDoc tags from the description', () => {
-    const component = createComponent({
-      ...createStringType(x),
-      description: 'Hey!\n@param event\nreturns {string}',
+      expect(propDef.description).toBe('Hey!');
     });
 
-    const { propDef } = extractPropsFromDocgen(component, DOCGEN_SECTION)[0];
+    it('should not remove newline characters of multilines description without JSDoc tags', () => {
+      const component = createComponent({
+        ...createStringType(x),
+        description: 'onClick description\nis a\nmulti-lines\ndescription',
+      });
 
-    expect(propDef.description).toBe('Hey!');
-  });
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
 
-  it('should not remove newline characters of multilines description without JSDoc tags', () => {
-    const component = createComponent({
-      ...createStringType(x),
-      description: 'onClick description\nis a\nmulti-lines\ndescription',
+      expect(propDef.description).toBe('onClick description\nis a\nmulti-lines\ndescription');
     });
 
-    const { propDef } = extractPropsFromDocgen(component, DOCGEN_SECTION)[0];
+    it('should not remove newline characters of multilines description with JSDoc tags', () => {
+      const component = createComponent({
+        ...createFuncType(x),
+        description: 'onClick description\nis a\nmulti-lines\ndescription\n@param event',
+      });
 
-    expect(propDef.description).toBe('onClick description\nis a\nmulti-lines\ndescription');
-  });
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
 
-  it('should not remove newline characters of multilines description with JSDoc tags', () => {
-    const component = createComponent({
-      ...createFuncType(x),
-      description: 'onClick description\nis a\nmulti-lines\ndescription\n@param event',
+      expect(propDef.description).toBe('onClick description\nis a\nmulti-lines\ndescription');
     });
 
-    const { propDef } = extractPropsFromDocgen(component, DOCGEN_SECTION)[0];
+    it('should not remove markdown from description without JSDoc tags', () => {
+      const component = createComponent({
+        ...createStringType(x),
+        description: 'onClick *emphasis*, **strong**, `formatted` description.',
+      });
 
-    expect(propDef.description).toBe('onClick description\nis a\nmulti-lines\ndescription');
-  });
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
 
-  it('should not remove markdown from description without JSDoc tags', () => {
-    const component = createComponent({
-      ...createStringType(x),
-      description: 'onClick *emphasis*, **strong**, `formatted` description.',
+      expect(propDef.description).toBe('onClick *emphasis*, **strong**, `formatted` description.');
     });
 
-    const { propDef } = extractPropsFromDocgen(component, DOCGEN_SECTION)[0];
+    it('should not remove markdown from description with JSDoc tags', () => {
+      const component = createComponent({
+        ...createFuncType(x),
+        description: 'onClick *emphasis*, **strong**, `formatted` description.\n@param event',
+      });
 
-    expect(propDef.description).toBe('onClick *emphasis*, **strong**, `formatted` description.');
-  });
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
 
-  it('should not remove markdown from description with JSDoc tags', () => {
-    const component = createComponent({
-      ...createFuncType(x),
-      description: 'onClick *emphasis*, **strong**, `formatted` description.\n@param event',
+      expect(propDef.description).toBe('onClick *emphasis*, **strong**, `formatted` description.');
     });
 
-    const { propDef } = extractPropsFromDocgen(component, DOCGEN_SECTION)[0];
+    it('should return null when the property is marked with @ignore', () => {
+      const component = createComponent({
+        ...createStringType(x),
+        description: 'onClick description\n@ignore',
+      });
 
-    expect(propDef.description).toBe('onClick *emphasis*, **strong**, `formatted` description.');
-  });
+      expect(extractComponentProps(component, DOCGEN_SECTION).length).toBe(0);
+    });
 
-  it('should return null when the property is marked with @ignore', () => {
-    const component = createComponent({
-      ...createStringType(x),
-      description: 'onClick description\n@ignore',
+    it('should provide raw @param tags', () => {
+      const component = createComponent({
+        ...createFuncType(x),
+        description:
+          'onClick description\n@param {SyntheticEvent} event - Original event.\n@param {string} value',
+      });
+
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
+
+      expect(propDef.description).toBe('onClick description');
+      expect(propDef.jsDocTags).toBeDefined();
+      expect(propDef.jsDocTags.params).toBeDefined();
+      expect(propDef.jsDocTags.params[0].name).toBe('event');
+      expect(propDef.jsDocTags.params[0].description).toBe('Original event.');
+      expect(propDef.jsDocTags.params[1].name).toBe('value');
+      expect(propDef.jsDocTags.params[1].description).toBeNull();
     });
 
-    expect(extractPropsFromDocgen(component, DOCGEN_SECTION).length).toBe(0);
-  });
+    it("should not return 'null' default value", () => {
+      const component = createComponent({
+        ...createStringType(x),
+        defaultValue: { value: 'null' },
+      });
 
-  it('should provide raw @param tags', () => {
-    const component = createComponent({
-      ...createFuncType(x),
-      description:
-        'onClick description\n@param {SyntheticEvent} event - Original event.\n@param {string} value',
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
+
+      expect(propDef.defaultValue).toBeNull();
     });
 
-    const { propDef } = extractPropsFromDocgen(component, DOCGEN_SECTION)[0];
+    it("should not return 'undefined' default value", () => {
+      const component = createComponent({
+        ...createStringType(x),
+        defaultValue: { value: 'undefined' },
+      });
+
+      const { propDef } = extractComponentProps(component, DOCGEN_SECTION)[0];
 
-    expect(propDef.description).toBe('onClick description');
-    expect(propDef.jsDocTags).toBeDefined();
-    expect(propDef.jsDocTags.params).toBeDefined();
-    expect(propDef.jsDocTags.params[0].name).toBe('event');
-    expect(propDef.jsDocTags.params[0].description).toBe('Original event.');
-    expect(propDef.jsDocTags.params[1].name).toBe('value');
-    expect(propDef.jsDocTags.params[1].description).toBeNull();
+      expect(propDef.defaultValue).toBeNull();
+    });
   });
 });

addons/docs/src/lib/docgen/extractDocgenProps.ts

@@ -3,7 +3,7 @@ import { PropDef } from '@storybook/components';
 import { Component } from '../../blocks/shared';
 import { ExtractedJsDoc, parseJsDoc } from '../jsdocParser';
 import { DocgenInfo, TypeSystem } from './types';
-import { getDocgenSection, isValidDocgenSection } from './utils';
+import { getDocgenSection, isValidDocgenSection, getDocgenDescription } from './utils';
 import { getPropDefFactory, PropDefFactory } from './createPropDef';
 
 export interface ExtractedProp {
@@ -31,7 +31,7 @@ const getTypeSystem = (docgenInfo: DocgenInfo): TypeSystem => {
   return TypeSystem.UNKNOWN;
 };
 
-export const extractPropsFromDocgen: ExtractProps = (component, section) => {
+export const extractComponentProps: ExtractProps = (component, section) => {
   const docgenSection = getDocgenSection(component, section);
 
   if (!isValidDocgenSection(docgenSection)) {
@@ -75,3 +75,7 @@ function extractProp(
 
   return null;
 }
+
+export function extractComponentDescription(component: Component): string {
+  return getDocgenDescription(component);
+}

addons/docs/src/lib/docgen/flow/createDefaultValue.ts

@@ -2,6 +2,7 @@ import { PropDefaultValue } from '@storybook/components';
 import { isNil } from 'lodash';
 import { DocgenPropDefaultValue, DocgenPropType } from '../types';
 import { createSummaryValue, isTooLongForDefaultValueSummary } from '../../utils';
+import { isDefaultValueBlacklisted } from '../utils/defaultValue';
 
 export function createDefaultValue(
   defaultValue: DocgenPropDefaultValue,
@@ -10,9 +11,11 @@ export function createDefaultValue(
   if (!isNil(defaultValue)) {
     const { value } = defaultValue;
 
-    return !isTooLongForDefaultValueSummary(value)
-      ? createSummaryValue(value)
-      : createSummaryValue(type.name, value);
+    if (!isDefaultValueBlacklisted(value)) {
+      return !isTooLongForDefaultValueSummary(value)
+        ? createSummaryValue(value)
+        : createSummaryValue(type.name, value);
+    }
   }
 
   return null;