[Pagination] Leverage @default over default values (#19966)

docs/src/modules/utils/defaultPropsHandler.js

@@ -1,4 +1,5 @@
 const astTypes = require('ast-types');
+const { parse: parseDoctrine } = require('doctrine');
 const { utils: docgenUtils } = require('react-docgen');
 
 const { getPropertyName, isReactForwardRefCall, printValue, resolveToValue } = docgenUtils;
@@ -8,7 +9,12 @@ const { getPropertyName, isReactForwardRefCall, printValue, resolveToValue } = d
 
 const { namedTypes: types } = astTypes;
 
-function getDefaultValue(path) {
+function getDefaultValue(propertyPath) {
+  if (!types.AssignmentPattern.check(propertyPath.get('value').node)) {
+    return null;
+  }
+  let path = propertyPath.get('value', 'right');
+
   let node = path.node;
   let defaultValue;
   if (types.Literal.check(node)) {
@@ -39,19 +45,38 @@ function getDefaultValue(path) {
   return null;
 }
 
+function getJsdocDefaultValue(jsdoc) {
+  const defaultTag = jsdoc.tags.find(tag => tag.title === 'default');
+  if (defaultTag === undefined) {
+    return undefined;
+  }
+  return { value: defaultTag.description };
+}
+
 function getDefaultValuesFromProps(properties, documentation) {
   properties
     .filter(propertyPath => types.Property.check(propertyPath.node))
-    // Don't evaluate property if component is functional and the node is not an AssignmentPattern
-    .filter(propertyPath => types.AssignmentPattern.check(propertyPath.get('value').node))
     .forEach(propertyPath => {
       const propName = getPropertyName(propertyPath);
       if (!propName) return;
 
       const propDescriptor = documentation.getPropDescriptor(propName);
-      const defaultValue = getDefaultValue(propertyPath.get('value', 'right'));
-      if (defaultValue) {
-        propDescriptor.defaultValue = defaultValue;
+
+      const jsdocDefaultValue = getJsdocDefaultValue(
+        parseDoctrine(propDescriptor.description, {
+          sloppy: true,
+        }),
+      );
+      const defaultValue = getDefaultValue(propertyPath);
+
+      if (jsdocDefaultValue != null && defaultValue != null) {
+        throw new Error(
+          `Can't have JavaScript default value and jsdoc @defaultValue in prop '${propName}'. Remove the @defaultValue if you need the JavaScript default value at runtime.`,
+        );
+      }
+      const usedDefaultValue = defaultValue || jsdocDefaultValue;
+      if (usedDefaultValue) {
+        propDescriptor.defaultValue = usedDefaultValue;
       }
     });
 }

packages/material-ui-lab/src/Pagination/Pagination.js

@@ -27,31 +27,29 @@ function defaultGetAriaLabel(type, page, selected) {
 }
 
 const Pagination = React.forwardRef(function Pagination(props, ref) {
-  /* eslint-disable no-unused-vars */
   const {
-    boundaryCount = 1,
+    boundaryCount,
     children,
     classes,
     className,
     color = 'standard',
-    count = 1,
-    defaultPage = 1,
-    disabled = false,
+    count,
+    defaultPage,
+    disabled,
     getItemAriaLabel: getAriaLabel = defaultGetAriaLabel,
-    hideNextButton = false,
-    hidePrevButton = false,
+    hideNextButton,
+    hidePrevButton,
     onChange,
     page,
     renderItem = item => <PaginationItem {...item} />,
     shape = 'round',
-    showFirstButton = false,
-    showLastButton = false,
-    siblingCount = 1,
+    showFirstButton,
+    showLastButton,
+    siblingCount,
     size = 'medium',
     variant = 'text',
     ...other
   } = props;
-  /* eslint-enable no-unused-vars */
 
   const { items } = usePagination({ ...props, componentName: 'Pagination' });
 
@@ -81,9 +79,11 @@ const Pagination = React.forwardRef(function Pagination(props, ref) {
   );
 });
 
+// @default tags synced with default values from usePagination
 Pagination.propTypes = {
   /**
    * Number of always visible pages at the beginning and end.
+   * @default 1
    */
   boundaryCount: PropTypes.number,
   /**
@@ -105,14 +105,17 @@ Pagination.propTypes = {
   color: PropTypes.oneOf(['default', 'primary', 'secondary']),
   /**
    * The total number of pages.
+   * @default 1
    */
   count: PropTypes.number,
   /**
    * The page selected by default when the component is uncontrolled.
+   * @default 1
    */
   defaultPage: PropTypes.number,
   /**
    * If `true`, all the pagination component will be disabled.
+   * @default false
    */
   disabled: PropTypes.bool,
   /**
@@ -128,10 +131,12 @@ Pagination.propTypes = {
   getItemAriaLabel: PropTypes.func,
   /**
    * If `true`, hide the next-page button.
+   * @default false
    */
   hideNextButton: PropTypes.bool,
   /**
    * If `true`, hide the previous-page button.
+   * @default false
    */
   hidePrevButton: PropTypes.bool,
   /**
@@ -158,14 +163,17 @@ Pagination.propTypes = {
   shape: PropTypes.oneOf(['round', 'rounded']),
   /**
    * If `true`, show the first-page button.
+   * @default false
    */
   showFirstButton: PropTypes.bool,
   /**
    * If `true`, show the last-page button.
+   * @default false
    */
   showLastButton: PropTypes.bool,
   /**
    * Number of always visible pages before and after the current page.
+   * @default 1
    */
   siblingCount: PropTypes.number,
   /**

packages/material-ui-lab/src/Pagination/usePagination.js

@@ -1,6 +1,7 @@
 import { useControlled } from '@material-ui/core/utils';
 
 export default function usePagination(props = {}) {
+  // keep default values in sync with @default tags in Pagination.propTypes
   const {
     boundaryCount: boundaryCountProp = 1,
     componentName = 'usePagination',