[Table] Add deprecation for renamed TablePagination props (#23789)

mui · Dec 2, 2020 · 11b7b76 · 11b7b76
1 parent 02b273d
commit 11b7b76
Show file tree

Hide file tree

Showing 19 changed files with 113 additions and 70 deletions.
diff --git a/docs/pages/api-docs/table-pagination.md b/docs/pages/api-docs/table-pagination.md
@@ -38,8 +38,10 @@ The `MuiTablePagination` name can be used for providing [default props](/customi
 | <span class="prop-name">labelRowsPerPage</span> | <span class="prop-type">node</span> | <span class="prop-default">'Rows per page:'</span> | Customize the rows per page label.<br>For localization purposes, you can use the provided [translations](/guides/localization/). |
 | <span class="prop-name">nextIconButtonProps</span> | <span class="prop-type">object</span> |  | Props applied to the next arrow [`IconButton`](/api/icon-button/) element. |
 | <span class="prop-name">nextIconButtonText</span> | <span class="prop-type">string</span> | <span class="prop-default">'Next page'</span> | Text label for the next arrow icon button.<br>For localization purposes, you can use the provided [translations](/guides/localization/). |
-| <span class="prop-name required">onChangePage<abbr title="required">*</abbr></span> | <span class="prop-type">func</span> |  | Callback fired when the page is changed.<br><br>**Signature:**<br>`function(event: object, page: number) => void`<br>*event:* The event source of the callback.<br>*page:* The page selected. |
-| <span class="prop-name">onChangeRowsPerPage</span> | <span class="prop-type">func</span> |  | Callback fired when the number of rows per page is changed.<br><br>**Signature:**<br>`function(event: object) => void`<br>*event:* The event source of the callback. |
+| ~~<span class="prop-name">onChangePage</span>~~ | <span class="prop-type">func</span> |  | *Deprecated*. Use the `onPageChange` prop instead.<br><br>Callback fired when the page is changed. |
+| ~~<span class="prop-name">onChangeRowsPerPage</span>~~ | <span class="prop-type">func</span> |  | *Deprecated*. Use the `onRowsPerPageChange` prop instead.<br><br>Callback fired when the number of rows per page is changed. |
+| <span class="prop-name required">onPageChange<abbr title="required">*</abbr></span> | <span class="prop-type">func</span> |  | Callback fired when the page is changed.<br><br>**Signature:**<br>`function(event: object, page: number) => void`<br>*event:* The event source of the callback.<br>*page:* The page selected. |
+| <span class="prop-name">onRowsPerPageChange</span> | <span class="prop-type">func</span> |  | Callback fired when the number of rows per page is changed.<br><br>**Signature:**<br>`function(event: object) => void`<br>*event:* The event source of the callback. |
 | <span class="prop-name required">page<abbr title="required">*</abbr></span> | <span class="prop-type">number</span> |  | The zero-based index of the current page. |
 | <span class="prop-name required">rowsPerPage<abbr title="required">*</abbr></span> | <span class="prop-type">number</span> |  | The number of rows per page. |
 | <span class="prop-name">rowsPerPageOptions</span> | <span class="prop-type">array</span> | <span class="prop-default">[10, 25, 50, 100]</span> | Customizes the options of the rows per page select field. If less than two options are available, no select field will be displayed. |

diff --git a/docs/src/pages/components/pagination/TablePagination.js b/docs/src/pages/components/pagination/TablePagination.js
@@ -19,9 +19,9 @@ export default function TablePaginationDemo() {
       component="div"
       count={100}
       page={page}
-      onChangePage={handleChangePage}
+      onPageChange={handleChangePage}
       rowsPerPage={rowsPerPage}
-      onChangeRowsPerPage={handleChangeRowsPerPage}
+      onRowsPerPageChange={handleChangeRowsPerPage}
     />
   );
 }
diff --git a/docs/src/pages/components/pagination/TablePagination.tsx b/docs/src/pages/components/pagination/TablePagination.tsx
@@ -21,9 +21,9 @@ export default function TablePaginationDemo() {
       component="div"
       count={100}
       page={page}
-      onChangePage={handleChangePage}
+      onPageChange={handleChangePage}
       rowsPerPage={rowsPerPage}
-      onChangeRowsPerPage={handleChangeRowsPerPage}
+      onRowsPerPageChange={handleChangeRowsPerPage}
     />
   );
 }
diff --git a/docs/src/pages/components/tables/CustomPaginationActionsTable.js b/docs/src/pages/components/tables/CustomPaginationActionsTable.js
@@ -25,22 +25,22 @@ const useStyles1 = makeStyles((theme) => ({
 function TablePaginationActions(props) {
   const classes = useStyles1();
   const theme = useTheme();
-  const { count, page, rowsPerPage, onChangePage } = props;
+  const { count, page, rowsPerPage, onPageChange } = props;
 
   const handleFirstPageButtonClick = (event) => {
-    onChangePage(event, 0);
+    onPageChange(event, 0);
   };
 
   const handleBackButtonClick = (event) => {
-    onChangePage(event, page - 1);
+    onPageChange(event, page - 1);
   };
 
   const handleNextButtonClick = (event) => {
-    onChangePage(event, page + 1);
+    onPageChange(event, page + 1);
   };
 
   const handleLastPageButtonClick = (event) => {
-    onChangePage(event, Math.max(0, Math.ceil(count / rowsPerPage) - 1));
+    onPageChange(event, Math.max(0, Math.ceil(count / rowsPerPage) - 1));
   };
 
   return (
@@ -75,7 +75,7 @@ function TablePaginationActions(props) {
 
 TablePaginationActions.propTypes = {
   count: PropTypes.number.isRequired,
-  onChangePage: PropTypes.func.isRequired,
+  onPageChange: PropTypes.func.isRequired,
   page: PropTypes.number.isRequired,
   rowsPerPage: PropTypes.number.isRequired,
 };
@@ -161,8 +161,8 @@ export default function CustomPaginationActionsTable() {
                 inputProps: { 'aria-label': 'rows per page' },
                 native: true,
               }}
-              onChangePage={handleChangePage}
-              onChangeRowsPerPage={handleChangeRowsPerPage}
+              onPageChange={handleChangePage}
+              onRowsPerPageChange={handleChangeRowsPerPage}
               ActionsComponent={TablePaginationActions}
             />
           </TableRow>

diff --git a/docs/src/pages/components/tables/CustomPaginationActionsTable.tsx b/docs/src/pages/components/tables/CustomPaginationActionsTable.tsx
@@ -27,28 +27,28 @@ interface TablePaginationActionsProps {
   count: number;
   page: number;
   rowsPerPage: number;
-  onChangePage: (event: React.MouseEvent<HTMLButtonElement>, newPage: number) => void;
+  onPageChange: (event: React.MouseEvent<HTMLButtonElement>, newPage: number) => void;
 }
 
 function TablePaginationActions(props: TablePaginationActionsProps) {
   const classes = useStyles1();
   const theme = useTheme();
-  const { count, page, rowsPerPage, onChangePage } = props;
+  const { count, page, rowsPerPage, onPageChange } = props;
 
   const handleFirstPageButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-    onChangePage(event, 0);
+    onPageChange(event, 0);
   };
 
   const handleBackButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-    onChangePage(event, page - 1);
+    onPageChange(event, page - 1);
   };
 
   const handleNextButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-    onChangePage(event, page + 1);
+    onPageChange(event, page + 1);
   };
 
   const handleLastPageButtonClick = (event: React.MouseEvent<HTMLButtonElement>) => {
-    onChangePage(event, Math.max(0, Math.ceil(count / rowsPerPage) - 1));
+    onPageChange(event, Math.max(0, Math.ceil(count / rowsPerPage) - 1));
   };
 
   return (
@@ -163,8 +163,8 @@ export default function CustomPaginationActionsTable() {
                 inputProps: { 'aria-label': 'rows per page' },
                 native: true,
               }}
-              onChangePage={handleChangePage}
-              onChangeRowsPerPage={handleChangeRowsPerPage}
+              onPageChange={handleChangePage}
+              onRowsPerPageChange={handleChangeRowsPerPage}
               ActionsComponent={TablePaginationActions}
             />
           </TableRow>

diff --git a/docs/src/pages/components/tables/EnhancedTable.js b/docs/src/pages/components/tables/EnhancedTable.js
@@ -341,8 +341,8 @@ export default function EnhancedTable() {
           count={rows.length}
           rowsPerPage={rowsPerPage}
           page={page}
-          onChangePage={handleChangePage}
-          onChangeRowsPerPage={handleChangeRowsPerPage}
+          onPageChange={handleChangePage}
+          onRowsPerPageChange={handleChangeRowsPerPage}
         />
       </Paper>
       <FormControlLabel

diff --git a/docs/src/pages/components/tables/EnhancedTable.tsx b/docs/src/pages/components/tables/EnhancedTable.tsx
@@ -369,8 +369,8 @@ export default function EnhancedTable() {
           count={rows.length}
           rowsPerPage={rowsPerPage}
           page={page}
-          onChangePage={handleChangePage}
-          onChangeRowsPerPage={handleChangeRowsPerPage}
+          onPageChange={handleChangePage}
+          onRowsPerPageChange={handleChangeRowsPerPage}
         />
       </Paper>
       <FormControlLabel

diff --git a/docs/src/pages/components/tables/StickyHeadTable.js b/docs/src/pages/components/tables/StickyHeadTable.js
@@ -122,8 +122,8 @@ export default function StickyHeadTable() {
         count={rows.length}
         rowsPerPage={rowsPerPage}
         page={page}
-        onChangePage={handleChangePage}
-        onChangeRowsPerPage={handleChangeRowsPerPage}
+        onPageChange={handleChangePage}
+        onRowsPerPageChange={handleChangeRowsPerPage}
       />
     </Paper>
   );

diff --git a/docs/src/pages/components/tables/StickyHeadTable.tsx b/docs/src/pages/components/tables/StickyHeadTable.tsx
@@ -138,8 +138,8 @@ export default function StickyHeadTable() {
         count={rows.length}
         rowsPerPage={rowsPerPage}
         page={page}
-        onChangePage={handleChangePage}
-        onChangeRowsPerPage={handleChangeRowsPerPage}
+        onPageChange={handleChangePage}
+        onRowsPerPageChange={handleChangeRowsPerPage}
       />
     </Paper>
   );

diff --git a/docs/src/pages/guides/api/api.md b/docs/src/pages/guides/api/api.md
@@ -98,6 +98,7 @@ This choice allows the shorthand notation:
 
 Most of the controlled component are controlled via the `value` and the `onChange` properties,
 however, the `open` / `onClose` / `onOpen` combination is used for display related state.
+In cases where there are multiple events, we put the noun first, and then the verb, for example: `onPageChange`, `onRowsChange`.
 
 ### boolean vs enum
 

diff --git a/docs/src/pages/guides/localization/Locales.js b/docs/src/pages/guides/localization/Locales.js
@@ -31,7 +31,7 @@ export default function Locales() {
           rowsPerPage={10}
           page={1}
           component="div"
-          onChangePage={() => {}}
+          onPageChange={() => {}}
         />
         <Pagination count={2000} color="primary" />
         <Rating defaultValue={4} name="locales" />

diff --git a/docs/src/pages/guides/localization/Locales.tsx b/docs/src/pages/guides/localization/Locales.tsx
@@ -33,7 +33,7 @@ export default function Locales() {
           rowsPerPage={10}
           page={1}
           component="div"
-          onChangePage={() => {}}
+          onPageChange={() => {}}
         />
         <Pagination count={2000} color="primary" />
         <Rating defaultValue={4} name="locales" />

diff --git a/packages/material-ui/src/TablePagination/TablePagination.d.ts b/packages/material-ui/src/TablePagination/TablePagination.d.ts
@@ -24,8 +24,23 @@ export interface TablePaginationTypeMap<P, D extends React.ElementType> {
       labelRowsPerPage?: React.ReactNode;
       nextIconButtonProps?: Partial<IconButtonProps>;
       nextIconButtonText?: string;
-      onChangePage: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
+      /**
+       * Callback fired when the page is changed.
+       *
+       * @param {object} event The event source of the callback.
+       * @param {number} page The page selected.
+       * @deprecated Use the onPageChange prop instead.
+       */
+      onChangePage?: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
+      onPageChange: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
+      /**
+       * Callback fired when the number of rows per page is changed.
+       *
+       * @param {object} event The event source of the callback.
+       * @deprecated Use the onRowsPerPageChange prop instead.
+       */
       onChangeRowsPerPage?: React.ChangeEventHandler<HTMLTextAreaElement | HTMLInputElement>;
+      onRowsPerPageChange?: React.ChangeEventHandler<HTMLTextAreaElement | HTMLInputElement>;
       page: number;
       rowsPerPage: number;
       rowsPerPageOptions?: Array<number | { value: number; label: string }>;

diff --git a/packages/material-ui/src/TablePagination/TablePagination.js b/packages/material-ui/src/TablePagination/TablePagination.js
@@ -2,6 +2,7 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { chainPropTypes } from '@material-ui/utils';
 import clsx from 'clsx';
+import deprecatedPropType from '../utils/deprecatedPropType';
 import withStyles from '../styles/withStyles';
 import InputBase from '../InputBase';
 import MenuItem from '../MenuItem';
@@ -88,14 +89,20 @@ const TablePagination = React.forwardRef(function TablePagination(props, ref) {
     labelRowsPerPage = 'Rows per page:',
     nextIconButtonProps,
     nextIconButtonText = 'Next page',
-    onChangePage,
-    onChangeRowsPerPage,
+    onChangePage: onChangePageProp,
+    onPageChange: onPageChangeProp,
+    onChangeRowsPerPage: onChangeRowsPerPageProp,
+    onRowsPerPageChange: onRowsPerPageChangeProp,
     page,
     rowsPerPage,
     rowsPerPageOptions = defaultRowsPerPageOptions,
     SelectProps = {},
     ...other
   } = props;
+
+  const onChangePage = onChangePageProp || onPageChangeProp;
+  const onChangeRowsPerPage = onChangeRowsPerPageProp || onRowsPerPageChangeProp;
+
   let colSpan;
 
   if (Component === TableCell || Component === 'td') {
@@ -160,7 +167,7 @@ const TablePagination = React.forwardRef(function TablePagination(props, ref) {
             'aria-label': nextIconButtonText,
             ...nextIconButtonProps,
           }}
-          onChangePage={onChangePage}
+          onPageChange={onChangePage}
           page={page}
           rowsPerPage={rowsPerPage}
         />
@@ -232,19 +239,37 @@ TablePagination.propTypes = {
    * For localization purposes, you can use the provided [translations](/guides/localization/).
    */
   nextIconButtonText: PropTypes.string,
+  /**
+   * Callback fired when the page is changed.
+   *
+   * @param {object} event The event source of the callback.
+   * @param {number} page The page selected.
+   * @deprecated Use the onPageChange prop instead.
+   */
+  onChangePage: deprecatedPropType(PropTypes.func, 'Use the `onPageChange` prop instead.'),
+  /**
+   * Callback fired when the number of rows per page is changed.
+   *
+   * @param {object} event The event source of the callback.
+   * @deprecated Use the onRowsPerPageChange prop instead.
+   */
+  onChangeRowsPerPage: deprecatedPropType(
+    PropTypes.func,
+    'Use the `onRowsPerPageChange` prop instead.',
+  ),
   /**
    * Callback fired when the page is changed.
    *
    * @param {object} event The event source of the callback.
    * @param {number} page The page selected.
    */
-  onChangePage: PropTypes.func.isRequired,
+  onPageChange: PropTypes.func.isRequired,
   /**
    * Callback fired when the number of rows per page is changed.
    *
    * @param {object} event The event source of the callback.
    */
-  onChangeRowsPerPage: PropTypes.func,
+  onRowsPerPageChange: PropTypes.func,
   /**
    * The zero-based index of the current page.
    */

diff --git a/packages/material-ui/src/TablePagination/TablePagination.spec.tsx b/packages/material-ui/src/TablePagination/TablePagination.spec.tsx
@@ -4,7 +4,7 @@ import TablePagination from '@material-ui/core/TablePagination';
 function classesTest() {
   const defaultProps = {
     count: 1,
-    onChangePage: () => {},
+    onPageChange: () => {},
     page: 1,
     rowsPerPage: 1,
   };