Add "sortProps" and "requiredPropsFirst" props to LayoutRenderer (#228)

* Add "sortProps" and "requiredPropsFirst" props to LayoutRenderer

* docs(changeset): Adds "sortProps" and "requiredPropsFirst" props to LayoutRenderer and HybridLayout

Co-authored-by: Andrew Campbell <[email protected]>

Author: AndrewOCC

.changeset/twenty-sheep-tie.md

@@ -0,0 +1,5 @@
+---
+'pretty-proptypes': minor
+---
+
+Adds "sortProps" and "requiredPropsFirst" props to LayoutRenderer and HybridLayout

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

@@ -40,13 +40,22 @@ const Description = ({ children }: { children: Node }) => (
 
 export default class HybridLayout extends Component<DynamicPropsProps> {
   render() {
-    const { props, heading, component, shouldCollapseProps } = this.props;
+    const {
+      props,
+      heading,
+      component,
+      shouldCollapseProps,
+      requiredPropsFirst,
+      sortProps
+    } = this.props;
 
     return (
       <PropsWrapper heading={heading}>
         <LayoutRenderer
           component={component}
           props={props}
+          requiredPropsFirst={requiredPropsFirst}
+          sortProps={sortProps}
           renderType={({
             typeValue,
             defaultValue,

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

@@ -26,18 +26,53 @@ type Inter = {
   types: Array<Obj | Gen>
 };
 
+type Prop = {
+  kind: string,
+  optional: boolean,
+  key: { kind: string, name: string },
+  value: { kind: string }
+};
+
 export type LayoutRendererProps = {
+  /**
+   * Types to render, passed directly from the output of extract-react-types-loader
+   */
   props?: {
     component?: Obj | Inter
   },
+  /** React Component to render props for. */
   component?: ComponentType<any>,
+  /** Custom components to render to end-users */
   components?: Components,
-  renderType: CommonProps => ComponentType<CommonProps>
+  /**
+   * Function to render each prop in the props list.
+   * Render props contain the prop's information, including name, description etc.
+   */
+  renderType: CommonProps => ComponentType<CommonProps>,
+  /**
+   * If true, required props will be placed first in the props array
+   */
+  requiredPropsFirst?: boolean,
+  /**
+   * Sorting function applied to props list.
+   * Given two prop objects, returns:
+   * - 0 to maintain order
+   * - < 0 if propA should render before propB
+   * - > 0 if propB should render before propA
+   */
+  sortProps?: (propA: Prop, propB: Prop) => number
 };
 
 const getProps = props => (props && props.component ? getPropTypes(props.component) : []);
 
-const LayoutRenderer: FC<LayoutRendererProps> = ({ props, component, components, ...rest }) => {
+const LayoutRenderer: FC<LayoutRendererProps> = ({
+  props,
+  component,
+  components,
+  requiredPropsFirst,
+  sortProps,
+  ...rest
+}) => {
   let resolvedProps = props;
   if (component) {
     /* $FlowFixMe the component prop is typed as a component because
@@ -65,7 +100,19 @@ const LayoutRenderer: FC<LayoutRendererProps> = ({ props, component, components,
     };
   }
 
-  return getProps(resolvedProps).map(propType =>
+  // Sort prop list
+  let finalProps = getProps(resolvedProps);
+  if (sortProps) finalProps.sort(sortProps);
+  if (requiredPropsFirst) {
+    finalProps.sort((propA, propB) => {
+      const propARequired = !(propA.optional || propA.default);
+      const propBRequired = !(propB.optional || propB.default);
+      if (propARequired === propBRequired) return 0;
+      return propARequired ? -1 : 1;
+    });
+  }
+
+  return finalProps.map(propType =>
     renderPropType(
       propType,
       { ...renderProps, components: { ...components, PropType: PrettyPropType } },

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

@@ -0,0 +1,83 @@
+// @flow
+
+import { mount, configure } from 'enzyme';
+import React from 'react';
+import Adapter from 'enzyme-adapter-react-16';
+import { extractReactTypes } from 'extract-react-types';
+import LayoutRenderer from './index';
+
+configure({ adapter: new Adapter() });
+
+const assembleComponent = (propTypes, defaultProps, type = 'typescript') => {
+  let file = `
+  class Component extends React.Component<${propTypes}> {
+    defaultProps = ${defaultProps}
+  }`;
+  return extractReactTypes(file, type);
+};
+
+test('requiredPropsFirst should place required props in front of other props', () => {
+  const propTypes = assembleComponent(
+    `{
+      /**
+       * Required, but with a default value. Should be rendered second
+       */ 
+      a: number,
+      /** 
+       * Optional, should be rendered third
+       */ 
+      b?: string,
+      /**
+       * Required, no default. Should be rendered first
+       */
+      c: boolean,  
+    }`,
+    `{a: 1}`
+  );
+
+  const order = [];
+
+  // $FlowFixMe - deliberately no children
+  mount(
+    <LayoutRenderer
+      props={propTypes}
+      requiredPropsFirst
+      renderType={props => {
+        order.push(props.name);
+        return <div />;
+      }}
+    />
+  );
+
+  expect(order[0]).toEqual('c');
+});
+
+test('sortProps should run sort function before applying requiredPropsFirst', () => {
+  const propTypes = assembleComponent(
+    `{
+      c?: number,
+      b?: string,
+      a?: boolean,  
+      e: string,
+      d: string,
+    }`,
+    `{a: 1}`
+  );
+
+  const order = [];
+
+  // $FlowFixMe - deliberately no children
+  mount(
+    <LayoutRenderer
+      props={propTypes}
+      sortProps={(propA, propB) => propA.key.name.localeCompare(propB.key.name)}
+      requiredPropsFirst
+      renderType={props => {
+        order.push(props.name);
+        return <div />;
+      }}
+    />
+  );
+
+  expect(order[0]).toEqual('d');
+});

stories/layout/Hybrid.stories.js

@@ -13,8 +13,14 @@ const Template = args => args.component;
 
 export const Base = Template.bind({});
 
+const props = {
+  component: TypeScriptComponent,
+  requiredPropsFirst: true,
+  heading: 'Primitive types'
+};
+
 Base.args = {
-  component: <HybridLayout component={TypeScriptComponent} heading="Primitive types" />
+  component: <HybridLayout {...props} />
 };
 
 export const WithReset = Template.bind({});
@@ -27,7 +33,7 @@ WithReset.args = {
           @import 'https://unpkg.com/@atlaskit/[email protected]/dist/bundle.css';
         `}
       />
-      <HybridLayout component={TypeScriptComponent} heading="Primitive types" />
+      <HybridLayout {...props} />
     </>
   )
 };

stories/layout/LayoutRenderer.stories.js

@@ -82,6 +82,7 @@ Base.args = {
       <h2>Primitive types</h2>
       <LayoutRenderer
         component={TypeScriptComponent}
+        requiredPropsFirst
         renderType={({
           typeValue,
           defaultValue,