[WNNMGDS-270] Update prop doc rendering (#622)

* Show children prop documentation and update component docs * Update autocomplete props * Hide prop docs with @HidePropDoc instead of _ * Fix tests * Update backstop references * PR feedback and rename flag to @hide-prop Co-authored-by: Scott Weber <[email protected]>
CMSgov · Feb 18, 2020 · 4ae2c28 · 4ae2c28
1 parent 8378bf8
commit 4ae2c28
Show file tree

Hide file tree

Showing 65 changed files with 53 additions and 32 deletions.
diff --git a/guides/WRITING-DOCUMENTATION.md b/guides/WRITING-DOCUMENTATION.md
@@ -215,7 +215,7 @@ Button.propTypes = {
 };
 ```
 
-For internal/private props that you don't want to be displayed in the documentation, prefix the prop with an underscore (ie. `_parentDefaultSelectedId`).
+For internal/private props that you don't want to be displayed in the documentation, include the **`@hide-prop`** flag in the React prop description (ie. `_selectedId` in `<VerticalNav>`).
 
 ## General documentation pages
 

diff --git a/packages/core/src/components/Alert/Alert.jsx b/packages/core/src/components/Alert/Alert.jsx
@@ -54,6 +54,9 @@ Alert.defaultProps = {
   role: 'region'
 };
 Alert.propTypes = {
+  /**
+   * The alert's body content
+   */
   children: PropTypes.node,
   /**
    * Text for the alert heading

diff --git a/packages/core/src/components/Autocomplete/Autocomplete.jsx b/packages/core/src/components/Autocomplete/Autocomplete.jsx
@@ -215,12 +215,13 @@ Autocomplete.propTypes = {
    */
   ariaClearLabel: PropTypes.string,
   /**
-   * Control the `TextField` autocomplete attribute. Changed to "off" to support accessibility. Chrome 70 appears to support this correct behavior in early testing.
-   *
-   * https://developer.mozilla.org/en-US/docs/Web/Security/Securing_your_site/Turning_off_form_autocompletion
+   * Control the `TextField` autocomplete attribute. Defaults to "off" to support accessibility. [Read more.](https://developer.mozilla.org/en-US/docs/Web/Security/Securing_your_site/Turning_off_form_autocompletion)
    */
   autoCompleteLabel: PropTypes.string,
-  children: PropTypes.node,
+  /**
+   * Must contain a `TextField` component
+   */
+  children: PropTypes.node.isRequired,
   /**
    * Additional classes to be added to the root element.
    * Useful for adding utility classes.
@@ -250,9 +251,7 @@ Autocomplete.propTypes = {
    */
   inputRef: PropTypes.func,
   /**
-   * Used to determine the string value for the selected item (which is used to compute the `inputValue`).
-   *
-   * Also see: https://github.com/paypal/downshift#itemtostring
+   * Used to determine the string value for the selected item (which is used to compute the `inputValue`). [Read more on downshift docs.](https://github.com/paypal/downshift#itemtostring)
    */
   itemToString: PropTypes.func,
   /**
@@ -285,15 +284,11 @@ Autocomplete.propTypes = {
    */
   noResultsMessage: PropTypes.node,
   /**
-   * Called when the user selects an item and the selected item has changed. Called with the item that was selected and the new state.
-   *
-   * Also see: https://github.com/paypal/downshift#onchange
+   * Called when the user selects an item and the selected item has changed. Called with the item that was selected and the new state. [Read more on downshift docs.](https://github.com/paypal/downshift#onchange)
    */
   onChange: PropTypes.func,
   /**
-   * Called when the child `TextField` value changes. Returns a String `inputValue`.
-   *
-   * Also see: https://github.com/paypal/downshift#oninputvaluechange
+   * Called when the child `TextField` value changes. Returns a String `inputValue`. [Read more on downshift docs.](https://github.com/paypal/downshift#oninputvaluechange)
    */
   onInputValueChange: PropTypes.func
 };

diff --git a/packages/core/src/components/Badge/Badge.jsx b/packages/core/src/components/Badge/Badge.jsx
@@ -23,10 +23,9 @@ Badge.propTypes = {
    */
   className: PropTypes.string,
   /**
-   * In most cases this will be the badge's label, but you could also use this
-   * to nest more advanced JSX.
+   * Label text or HTML.
    */
-  children: PropTypes.oneOfType([PropTypes.node, PropTypes.string]).isRequired,
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node]).isRequired,
   /**
    * Sets the font size of the Badge
    */

diff --git a/packages/core/src/components/Button/Button.jsx b/packages/core/src/components/Button/Button.jsx
@@ -107,7 +107,10 @@ export class Button extends React.PureComponent {
 
 Button.defaultProps = { type: 'button' };
 Button.propTypes = {
-  children: PropTypes.node.isRequired,
+  /**
+   * Label text or HTML
+   */
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node]).isRequired,
   /**
    * Additional classes to be added to the root button element.
    * Useful for adding utility classes.
@@ -136,7 +139,7 @@ Button.propTypes = {
    */
   onClick: PropTypes.func,
   /**
-   * (Deprecated) Access a reference to the `button` or `a` element. Please use `inputRef` instead.
+   * @hide-prop [Deprecated] Access a reference to the `button` or `a` element. Please use `inputRef` instead.
    */
   buttonRef: PropTypes.func,
   size: PropTypes.oneOf(['small', 'big']),

diff --git a/packages/core/src/components/ChoiceList/Choice.jsx b/packages/core/src/components/ChoiceList/Choice.jsx
@@ -145,7 +145,7 @@ Choice.propTypes = {
   /**
    * Label text or HTML.
    */
-  children: PropTypes.node.isRequired,
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node]).isRequired,
   /**
    * Sets the input's `checked` state. Use this in combination with `onChange`
    * for a controlled component; otherwise, set `defaultChecked`.
@@ -200,7 +200,7 @@ Choice.propTypes = {
    */
   inversed: PropTypes.bool,
   /**
-   * (Deprecated) Placement of the input relative to the text label
+   * @hide-prop [Deprecated] Placement of the input relative to the text label
    */
   inputPlacement: PropTypes.oneOf(['left', 'right']),
   size: PropTypes.oneOf(['small']),

diff --git a/packages/core/src/components/ChoiceList/ChoiceList.jsx b/packages/core/src/components/ChoiceList/ChoiceList.jsx
@@ -247,7 +247,7 @@ ChoiceList.propTypes = {
    */
   type: PropTypes.oneOf(['checkbox', 'radio']),
   /**
-   * (Deprecated) Adds `aria-label` attribute if component renders a select
+   * @hide-prop [Deprecated] Adds `aria-label` attribute if component renders a select
    */
   ariaLabel: PropTypes.string
 };

diff --git a/packages/core/src/components/Dropdown/Dropdown.jsx b/packages/core/src/components/Dropdown/Dropdown.jsx
@@ -158,7 +158,7 @@ Dropdown.propTypes = {
    */
   fieldClassName: PropTypes.string,
   /**
-   * (Deprecated) Access a reference to the `select` element. Please use `inputRef` instead.
+   * @hide-prop [Deprecated] Access a reference to the `select` element. Please use `inputRef` instead.
    */
   fieldRef: PropTypes.func,
   /**

diff --git a/packages/core/src/components/FormLabel/FormLabel.jsx b/packages/core/src/components/FormLabel/FormLabel.jsx
@@ -80,7 +80,10 @@ export class FormLabel extends React.PureComponent {
 
 FormLabel.defaultProps = { component: 'label' };
 FormLabel.propTypes = {
-  children: PropTypes.node.isRequired,
+  /**
+   * Label text or HTML.
+   */
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node]).isRequired,
   /**
    * Additional classes to be added to the root element.
    */
@@ -108,7 +111,7 @@ FormLabel.propTypes = {
    */
   inversed: PropTypes.bool,
   /**
-   * (Deprecated) Additional classes to be added to the label text. Please use `textClassName` instead.
+   * @hide-prop [Deprecated] Additional classes to be added to the label text. Please use `textClassName` instead.
    */
   labelClassName: PropTypes.string,
   /**

diff --git a/packages/core/src/components/Review/Review.jsx b/packages/core/src/components/Review/Review.jsx
@@ -51,6 +51,9 @@ Review.defaultProps = {
 };
 
 Review.propTypes = {
+  /**
+   * `Review` component's body HTML.
+   */
   children: PropTypes.node.isRequired,
   className: PropTypes.string,
   /**

diff --git a/packages/core/src/components/SkipNav/SkipNav.jsx b/packages/core/src/components/SkipNav/SkipNav.jsx
@@ -14,7 +14,10 @@ SkipNav.defaultProps = {
 };
 
 SkipNav.propTypes = {
-  children: PropTypes.node.isRequired,
+  /**
+   * Skip nav label
+   */
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node]).isRequired,
   /**
    * The anchor or target for the link (where the link will jump the user to)
    */

diff --git a/packages/core/src/components/Tabs/Tab.jsx b/packages/core/src/components/Tabs/Tab.jsx
@@ -67,7 +67,10 @@ Tab.defaultProps = {
 };
 
 Tab.propTypes = {
-  children: PropTypes.node.isRequired,
+  /**
+   * Tab label text or HTML.
+   */
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node]).isRequired,
   /**
    * Additional classes to be added to the root tab element.
    */

diff --git a/packages/core/src/components/Tabs/Tabs.jsx b/packages/core/src/components/Tabs/Tabs.jsx
@@ -190,6 +190,9 @@ export class Tabs extends React.PureComponent {
 }
 
 Tabs.propTypes = {
+  /**
+   * Must only contain `TabPanel` components
+   */
   children: PropTypes.node.isRequired,
   /**
    * Sets the initial selected `TabPanel` state. If this isn't set, the first

diff --git a/packages/core/src/components/Tabs/_Tabs.docs.scss b/packages/core/src/components/Tabs/_Tabs.docs.scss
@@ -33,6 +33,8 @@ Style guide: components.tabs.react-tabpanel
 /*
 `<Tab>`
 
+@hide-example
+
 @react-component Tab
 
 Style guide: components.tabs.react-tab

diff --git a/packages/core/src/components/TextField/TextField.jsx b/packages/core/src/components/TextField/TextField.jsx
@@ -184,7 +184,7 @@ TextField.propTypes = {
    */
   fieldClassName: PropTypes.string,
   /**
-   * (Deprecated) Access a reference to the `input` or `textarea` element. Please use `inputRef` instead.
+   * @hide-prop [Deprecated] Access a reference to the `input` or `textarea` element. Please use `inputRef` instead.
    */
   fieldRef: PropTypes.func,
   /**

diff --git a/packages/core/src/components/VerticalNav/VerticalNavItem.jsx b/packages/core/src/components/VerticalNav/VerticalNavItem.jsx
@@ -143,7 +143,9 @@ VerticalNavItem.defaultProps = {
 };
 
 VerticalNavItem.propTypes = {
-  // This gets passed through from the parent VerticalNav to a nested VerticalNav
+  /**
+   * @hide-prop This gets passed through from the parent VerticalNav to a nested VerticalNav
+   */
   _selectedId: PropTypes.string,
   /**
    * Aria label for the toggle button when the sub-navigation is collapsed

diff --git a/packages/docs/src/scripts/components/ReactPropDocs.jsx b/packages/docs/src/scripts/components/ReactPropDocs.jsx
@@ -10,9 +10,11 @@ class ReactPropDocs extends React.PureComponent {
     const props = Object.getOwnPropertyNames(this.props.propDocs);
 
     return props.map(prop => {
-      if (prop === 'children' || prop.match(/^_/)) return null;
-
-      return <ReactPropDoc key={prop} name={prop} {...this.props.propDocs[prop]} />;
+      // Hides docs for react props with `@hide-prop` tag in the description
+      const description = this.props.propDocs[prop].description;
+      if (!description.match(/@hide-prop/i)) {
+        return <ReactPropDoc key={prop} name={prop} {...this.props.propDocs[prop]} />;
+      }
     });
   }
 

diff --git a/...ps_reference/backstop_default_CMSDS_-_Components_-_Alert_0_document_0_phone.png b/...ps_reference/backstop_default_CMSDS_-_Components_-_Alert_0_document_0_phone.png
diff --git a/...s_reference/backstop_default_CMSDS_-_Components_-_Alert_0_document_1_tablet.png b/...s_reference/backstop_default_CMSDS_-_Components_-_Alert_0_document_1_tablet.png
diff --git a/..._reference/backstop_default_CMSDS_-_Components_-_Alert_0_document_2_desktop.png b/..._reference/backstop_default_CMSDS_-_Components_-_Alert_0_document_2_desktop.png
diff --git a/...rence/backstop_default_CMSDS_-_Components_-_Autocomplete_0_document_0_phone.png b/...rence/backstop_default_CMSDS_-_Components_-_Autocomplete_0_document_0_phone.png
diff --git a/...ence/backstop_default_CMSDS_-_Components_-_Autocomplete_0_document_1_tablet.png b/...ence/backstop_default_CMSDS_-_Components_-_Autocomplete_0_document_1_tablet.png
diff --git a/...nce/backstop_default_CMSDS_-_Components_-_Autocomplete_0_document_2_desktop.png b/...nce/backstop_default_CMSDS_-_Components_-_Autocomplete_0_document_2_desktop.png
diff --git a/...ps_reference/backstop_default_CMSDS_-_Components_-_Badge_0_document_0_phone.png b/...ps_reference/backstop_default_CMSDS_-_Components_-_Badge_0_document_0_phone.png
diff --git a/...s_reference/backstop_default_CMSDS_-_Components_-_Badge_0_document_1_tablet.png b/...s_reference/backstop_default_CMSDS_-_Components_-_Badge_0_document_1_tablet.png
diff --git a/..._reference/backstop_default_CMSDS_-_Components_-_Badge_0_document_2_desktop.png b/..._reference/backstop_default_CMSDS_-_Components_-_Badge_0_document_2_desktop.png
diff --git a/...s_reference/backstop_default_CMSDS_-_Components_-_Button_0_document_0_phone.png b/...s_reference/backstop_default_CMSDS_-_Components_-_Button_0_document_0_phone.png
diff --git a/..._reference/backstop_default_CMSDS_-_Components_-_Button_0_document_1_tablet.png b/..._reference/backstop_default_CMSDS_-_Components_-_Button_0_document_1_tablet.png
diff --git a/...reference/backstop_default_CMSDS_-_Components_-_Button_0_document_2_desktop.png b/...reference/backstop_default_CMSDS_-_Components_-_Button_0_document_2_desktop.png
diff --git a/...ce/backstop_default_CMSDS_-_Components_-_Checkbox__Radio_0_document_0_phone.png b/...ce/backstop_default_CMSDS_-_Components_-_Checkbox__Radio_0_document_0_phone.png
diff --git a/...e/backstop_default_CMSDS_-_Components_-_Checkbox__Radio_0_document_1_tablet.png b/...e/backstop_default_CMSDS_-_Components_-_Checkbox__Radio_0_document_1_tablet.png
diff --git a/.../backstop_default_CMSDS_-_Components_-_Checkbox__Radio_0_document_2_desktop.png b/.../backstop_default_CMSDS_-_Components_-_Checkbox__Radio_0_document_2_desktop.png
diff --git a/...reference/backstop_default_CMSDS_-_Components_-_Dropdown_0_document_0_phone.png b/...reference/backstop_default_CMSDS_-_Components_-_Dropdown_0_document_0_phone.png
diff --git a/...eference/backstop_default_CMSDS_-_Components_-_Dropdown_0_document_1_tablet.png b/...eference/backstop_default_CMSDS_-_Components_-_Dropdown_0_document_1_tablet.png
diff --git a/...ference/backstop_default_CMSDS_-_Components_-_Dropdown_0_document_2_desktop.png b/...ference/backstop_default_CMSDS_-_Components_-_Dropdown_0_document_2_desktop.png
diff --git a/...backstop_default_CMSDS_-_Components_-_Form_label__legend_0_document_0_phone.png b/...backstop_default_CMSDS_-_Components_-_Form_label__legend_0_document_0_phone.png
diff --git a/...ackstop_default_CMSDS_-_Components_-_Form_label__legend_0_document_1_tablet.png b/...ackstop_default_CMSDS_-_Components_-_Form_label__legend_0_document_1_tablet.png
diff --git a/...ckstop_default_CMSDS_-_Components_-_Form_label__legend_0_document_2_desktop.png b/...ckstop_default_CMSDS_-_Components_-_Form_label__legend_0_document_2_desktop.png
diff --git a/...erence/backstop_default_CMSDS_-_Components_-_Help_drawer_0_document_0_phone.png b/...erence/backstop_default_CMSDS_-_Components_-_Help_drawer_0_document_0_phone.png
diff --git a/...rence/backstop_default_CMSDS_-_Components_-_Help_drawer_0_document_1_tablet.png b/...rence/backstop_default_CMSDS_-_Components_-_Help_drawer_0_document_1_tablet.png
diff --git a/...ence/backstop_default_CMSDS_-_Components_-_Help_drawer_0_document_2_desktop.png b/...ence/backstop_default_CMSDS_-_Components_-_Help_drawer_0_document_2_desktop.png
diff --git a/...rence/backstop_default_CMSDS_-_Components_-_Masked_Field_0_document_0_phone.png b/...rence/backstop_default_CMSDS_-_Components_-_Masked_Field_0_document_0_phone.png
diff --git a/...ence/backstop_default_CMSDS_-_Components_-_Masked_Field_0_document_1_tablet.png b/...ence/backstop_default_CMSDS_-_Components_-_Masked_Field_0_document_1_tablet.png
diff --git a/...nce/backstop_default_CMSDS_-_Components_-_Masked_Field_0_document_2_desktop.png b/...nce/backstop_default_CMSDS_-_Components_-_Masked_Field_0_document_2_desktop.png
diff --git a/...rence/backstop_default_CMSDS_-_Components_-_Modal_Dialog_0_document_0_phone.png b/...rence/backstop_default_CMSDS_-_Components_-_Modal_Dialog_0_document_0_phone.png
diff --git a/...ence/backstop_default_CMSDS_-_Components_-_Modal_Dialog_0_document_1_tablet.png b/...ence/backstop_default_CMSDS_-_Components_-_Modal_Dialog_0_document_1_tablet.png
diff --git a/...nce/backstop_default_CMSDS_-_Components_-_Modal_Dialog_0_document_2_desktop.png b/...nce/backstop_default_CMSDS_-_Components_-_Modal_Dialog_0_document_2_desktop.png
diff --git a/..._reference/backstop_default_CMSDS_-_Components_-_Skipnav_0_document_0_phone.png b/..._reference/backstop_default_CMSDS_-_Components_-_Skipnav_0_document_0_phone.png
diff --git a/...reference/backstop_default_CMSDS_-_Components_-_Skipnav_0_document_1_tablet.png b/...reference/backstop_default_CMSDS_-_Components_-_Skipnav_0_document_1_tablet.png
diff --git a/...eference/backstop_default_CMSDS_-_Components_-_Skipnav_0_document_2_desktop.png b/...eference/backstop_default_CMSDS_-_Components_-_Skipnav_0_document_2_desktop.png
diff --git a/...aps_reference/backstop_default_CMSDS_-_Components_-_Tabs_0_document_0_phone.png b/...aps_reference/backstop_default_CMSDS_-_Components_-_Tabs_0_document_0_phone.png
diff --git a/...ps_reference/backstop_default_CMSDS_-_Components_-_Tabs_0_document_1_tablet.png b/...ps_reference/backstop_default_CMSDS_-_Components_-_Tabs_0_document_1_tablet.png
diff --git a/...s_reference/backstop_default_CMSDS_-_Components_-_Tabs_0_document_2_desktop.png b/...s_reference/backstop_default_CMSDS_-_Components_-_Tabs_0_document_2_desktop.png
diff --git a/...eference/backstop_default_CMSDS_-_Components_-_Textfield_0_document_0_phone.png b/...eference/backstop_default_CMSDS_-_Components_-_Textfield_0_document_0_phone.png
diff --git a/...ference/backstop_default_CMSDS_-_Components_-_Textfield_0_document_1_tablet.png b/...ference/backstop_default_CMSDS_-_Components_-_Textfield_0_document_1_tablet.png
diff --git a/...erence/backstop_default_CMSDS_-_Components_-_Textfield_0_document_2_desktop.png b/...erence/backstop_default_CMSDS_-_Components_-_Textfield_0_document_2_desktop.png
diff --git a/...ackstop_default_CMSDS_-_Components_-_Vertical_Navigation_0_document_0_phone.png b/...ackstop_default_CMSDS_-_Components_-_Vertical_Navigation_0_document_0_phone.png
diff --git a/...ckstop_default_CMSDS_-_Components_-_Vertical_Navigation_0_document_1_tablet.png b/...ckstop_default_CMSDS_-_Components_-_Vertical_Navigation_0_document_1_tablet.png
diff --git a/...kstop_default_CMSDS_-_Components_-_Vertical_Navigation_0_document_2_desktop.png b/...kstop_default_CMSDS_-_Components_-_Vertical_Navigation_0_document_2_desktop.png
diff --git a/...erence/backstop_default_CMSDS_-_Patterns_-_External_Link_0_document_0_phone.png b/...erence/backstop_default_CMSDS_-_Patterns_-_External_Link_0_document_0_phone.png
diff --git a/...rence/backstop_default_CMSDS_-_Patterns_-_External_Link_0_document_1_tablet.png b/...rence/backstop_default_CMSDS_-_Patterns_-_External_Link_0_document_1_tablet.png
diff --git a/...ence/backstop_default_CMSDS_-_Patterns_-_External_Link_0_document_2_desktop.png b/...ence/backstop_default_CMSDS_-_Patterns_-_External_Link_0_document_2_desktop.png
diff --git a/...aps_reference/backstop_default_CMSDS_-_Patterns_-_Review_0_document_0_phone.png b/...aps_reference/backstop_default_CMSDS_-_Patterns_-_Review_0_document_0_phone.png
diff --git a/...ps_reference/backstop_default_CMSDS_-_Patterns_-_Review_0_document_1_tablet.png b/...ps_reference/backstop_default_CMSDS_-_Patterns_-_Review_0_document_1_tablet.png
diff --git a/...s_reference/backstop_default_CMSDS_-_Patterns_-_Review_0_document_2_desktop.png b/...s_reference/backstop_default_CMSDS_-_Patterns_-_Review_0_document_2_desktop.png
-Original file line number
+Diff line change
@@ Expand Up / @@ -215,7 +215,7 @@ Button.propTypes = { @@
     };
     ```
-    For internal/private props that you don't want to be displayed in the documentation, prefix the prop with an underscore (ie. `_parentDefaultSelectedId`).
+    For internal/private props that you don't want to be displayed in the documentation, include the **`@hide-prop`** flag in the React prop description (ie. `_selectedId` in `<VerticalNav>`).
     ## General documentation pages
@@ Expand Down @@