Prop table permalink (#224)

* Introduce a mechanism that allows each prop to have a permalink via HTML anchors.

Under the hood the rendering components get access to a 'componentDisplayName' which can be used as a composed 'id' to create unique anchor values.
For all out-of-the-box layouts this has been implemented as a simple change of background-color, for a custom 'LayoutRenderer' you can just use whatever styles you prefer.

* docs(changeset): Introduces new functionality to enable permalinks to each section of a props list. It's done in a backwards-compatible manner requiring no code changes for a dependency bump, but you might want to double check styles are suitable to the surroundings of where the props are displayed.

* Use styles blessed by design

* More defensive approach when handling 'component'

Co-authored-by: Klaus Paiva <[email protected]>

Author: klauspaiva

.changeset/fifty-carrots-hope.md

@@ -0,0 +1,6 @@
+---
+'babel-plugin-extract-react-types': minor
+'pretty-proptypes': minor
+---
+
+Introduces new functionality enabling permalinks to each section of a props list. It's done in a backwards-compatible manner requiring no code changes for a dependency bump, but you might want to double check styles are suitable to the surroundings of where the props are displayed.

packages/babel-plugin-extract-react-types/__snapshots__/index.test.js.snap

@@ -41,7 +41,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow arrow function 1`] = `
@@ -85,7 +86,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow arrow function export default identifier 1`] = `
@@ -132,7 +134,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow arrow function then export 1`] = `
@@ -179,7 +182,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow class 1`] = `
@@ -226,7 +230,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow class declaration export default identifier 1`] = `
@@ -276,7 +281,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow class declaration then export 1`] = `
@@ -326,7 +332,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow default class 1`] = `
@@ -373,7 +380,56 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
+`;
+
+exports[`flow default export with named identifier 1`] = `
+"// @flow
+type Props = {
+  /** this does something */
+  wow: boolean
+};
+
+const CustomComponent = (props: Props) => {
+  return null;
+};
+
+export default CustomComponent;
+CustomComponent.___types = {
+  \\"kind\\": \\"generic\\",
+  \\"value\\": {
+    \\"kind\\": \\"object\\",
+    \\"members\\": [{
+      \\"kind\\": \\"property\\",
+      \\"key\\": {
+        \\"kind\\": \\"id\\",
+        \\"name\\": \\"wow\\"
+      },
+      \\"value\\": {
+        \\"kind\\": \\"boolean\\"
+      },
+      \\"optional\\": false,
+      \\"leadingComments\\": [{
+        \\"type\\": \\"commentBlock\\",
+        \\"value\\": \\"this does something\\",
+        \\"raw\\": \\"* this does something \\"
+      }]
+    }],
+    \\"leadingComments\\": [{
+      \\"type\\": \\"commentLine\\",
+      \\"value\\": \\"@flow\\",
+      \\"raw\\": \\" @flow\\"
+    }],
+    \\"referenceIdName\\": \\"Props\\"
+  },
+  \\"name\\": {
+    \\"kind\\": \\"id\\",
+    \\"name\\": \\"CustomComponent\\",
+    \\"type\\": null
+  }
+};
+CustomComponent.___displayName = \\"CustomComponent\\";"
 `;
 
 exports[`flow default function declaration 1`] = `
@@ -420,7 +476,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow export default function declaration 1`] = `
@@ -465,7 +522,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow forwardRef 1`] = `
@@ -509,7 +567,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow forwardRef function expression 1`] = `
@@ -553,7 +612,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow forwardRef memo arrow function 1`] = `
@@ -597,7 +657,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow forwardRef memo function expression 1`] = `
@@ -641,7 +702,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow function declaration 1`] = `
@@ -685,7 +747,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`flow memo 1`] = `
@@ -729,7 +792,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`typescript default 1`] = `
@@ -754,7 +818,8 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;
 
 exports[`typescript named 1`] = `
@@ -779,5 +844,6 @@ SomeComponent.___types = {
     \\"name\\": \\"SomeComponent\\",
     \\"type\\": null
   }
-};"
+};
+SomeComponent.___displayName = \\"SomeComponent\\";"
 `;

packages/babel-plugin-extract-react-types/index.js

@@ -15,7 +15,7 @@ module.exports = babel => {
           findExportedComponents(programPath, typeSystem, state.file.filename).forEach(
             ({ name, component }) => {
               // TODO: handle when name is null
-              // it will only happen when it's the default export
+              // it will only happen when it's a default and anonymous export
               // generate something like this
               // export default (var someName = function() {}, someName.___types = theTypes, someName)
               if (name !== null) {
@@ -28,6 +28,15 @@ module.exports = babel => {
                     )
                   )
                 );
+                programPath.node.body.push(
+                  t.expressionStatement(
+                    t.assignmentExpression(
+                      '=',
+                      t.memberExpression(t.identifier(name), t.identifier('___displayName')),
+                      t.stringLiteral(name)
+                    )
+                  )
+                );
               }
             }
           );

packages/babel-plugin-extract-react-types/index.test.js

@@ -259,6 +259,23 @@ let flowCases = [
 
       export { SomeComponent }
       `
+  },
+  {
+    name: 'default export with named identifier',
+    code: `
+    // @flow
+
+    type Props = {
+      /** this does something */
+      wow: boolean
+    };
+    
+    const CustomComponent = (props: Props) => {
+      return null;
+    };  
+
+    export default CustomComponent
+    `
   }
 ];
 

packages/pretty-proptypes/src/HybridLayout/index.js

@@ -48,9 +48,11 @@ export default class HybridLayout extends Component<DynamicPropsProps> {
             required,
             name,
             type,
+            componentDisplayName,
             components: Comp
           }) => (
             <table
+              {...(componentDisplayName ? { id: `${componentDisplayName}-${name}` } : null)}
               css={css`
                 width: 100%;
                 border-collapse: collapse;
@@ -71,6 +73,11 @@ export default class HybridLayout extends Component<DynamicPropsProps> {
                 tbody {
                   border-bottom: none;
                 }
+
+                &:target,
+                &:target > caption {
+                  background: #e9f2ff;
+                }
               `}
             >
               <caption

packages/pretty-proptypes/src/LayoutRenderer/index.js

@@ -55,10 +55,20 @@ const LayoutRenderer: FC<LayoutRendererProps> = ({ props, component, components,
     }
   }
 
+  let renderProps = rest;
+  // ensure displayName passes through, assuming it has been captured
+  // $FlowFixMe as mentioned above, the typing for `component` is a bit off here...
+  if (component && component.___displayName) {
+    renderProps = {
+      ...rest,
+      componentDisplayName: String(component.___displayName)
+    };
+  }
+
   return getProps(resolvedProps).map(propType =>
     renderPropType(
       propType,
-      { ...rest, components: { ...components, PropType: PrettyPropType } },
+      { ...renderProps, components: { ...components, PropType: PrettyPropType } },
       rest.renderType
     )
   );

packages/pretty-proptypes/src/PrettyConvert/AddBrackets.js

@@ -2,7 +2,7 @@
 /** @jsx jsx */
 import { jsx } from '@emotion/core';
 import { Component, ComponentType, Fragment, type Node } from 'react';
-import ExpanderDefault from '../Components/Expander';
+import ExpanderDefault from '../components/Expander';
 
 type Props = {
   openBracket: string,

packages/pretty-proptypes/src/Prop/index.js

@@ -12,6 +12,10 @@ const PropTypeWrapper = (props: { children: Node }) => (
   <div
     css={css`
       margin-top: ${gridSize * 4}px;
+
+      &:target {
+        background: #e9f2ff;
+      }
     `}
     {...props}
   />
@@ -29,10 +33,20 @@ export default class Prop extends Component<PropProps> {
   render() {
     let { shapeComponent: ShapeComponent, ...commonProps } = this.props;
 
-    let { defaultValue, description, name, required, type, components } = commonProps;
+    let {
+      defaultValue,
+      description,
+      name,
+      required,
+      type,
+      components,
+      componentDisplayName
+    } = commonProps;
 
     return (
-      <PropTypeWrapper>
+      <PropTypeWrapper
+        {...(componentDisplayName ? { id: `${componentDisplayName}-${name}` } : null)}
+      >
         <PropTypeHeading name={name} required={required} type={type} defaultValue={defaultValue} />
         {description && <components.Description>{md([description])}</components.Description>}
         <ShapeComponent {...commonProps} />

packages/pretty-proptypes/src/Props/index.js

@@ -68,9 +68,19 @@ export default class Props extends Component<DynamicPropsProps> {
     let propTypes = getProps(props);
     if (!propTypes) return null;
 
+    let renderProps = rest;
+    // ensure displayName passes through, assuming it has been captured
+    // $FlowFixMe as mentioned above, the typing for `component` is a bit off here...
+    if (component && component.___displayName) {
+      renderProps = {
+        ...rest,
+        componentDisplayName: String(component.___displayName)
+      };
+    }
+
     return (
       <PropsWrapper heading={heading}>
-        {propTypes.map(propType => renderPropType(propType, rest, Prop))}
+        {propTypes.map(propType => renderPropType(propType, renderProps, Prop))}
       </PropsWrapper>
     );
   }