[Pagination] Introduce new component (#19049)

docs/pages/api/pagination-item.js

@@ -0,0 +1,7 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import markdown from './pagination-item.md';
+
+export default function Page() {
+  return <MarkdownDocs markdown={markdown} />;
+}

docs/pages/api/pagination-item.md

@@ -0,0 +1,75 @@
+---
+filename: /packages/material-ui-lab/src/PaginationItem/PaginationItem.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# PaginationItem API
+
+<p class="description">The API documentation of the PaginationItem React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import PaginationItem from '@material-ui/lab/PaginationItem';
+// or
+import { PaginationItem } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name">color</span> | <span class="prop-type">'standard'<br>&#124;&nbsp;'primary'<br>&#124;&nbsp;'secondary'</span> | <span class="prop-default">'standard'</span> | The active color. |
+| <span class="prop-name">component</span> | <span class="prop-type">elementType</span> |  | The component used for the root node. Either a string to use a DOM element or a component. |
+| <span class="prop-name">disabled</span> | <span class="prop-type">bool</span> | <span class="prop-default">false</span> | If `true`, the item will be disabled. |
+| <span class="prop-name">getAriaLabel</span> | <span class="prop-type">func</span> | <span class="prop-default">function defaultGetAriaLabel(type, page, selected) {  if (type === 'page') {    return `${selected ? '' : 'go to '}page ${page}`;  }  return `Go to ${type} page`;}</span> | Accepts a function which returns a string value that provides a user-friendly name for the current page.<br><br>**Signature:**<br>`function(type?: string, page: number, selected: bool) => string`<br>*type:* The link or button type to format ('page' | 'first' | 'last' | 'next' | 'previous').<br>*page:* The page number to format.<br>*selected:* If true, the current page is selected. |
+| <span class="prop-name">onClick</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">page</span> | <span class="prop-type">number</span> |  | The current page number. |
+| <span class="prop-name">selected</span> | <span class="prop-type">bool</span> |  | If `true` the pagination item is selected. |
+| <span class="prop-name">shape</span> | <span class="prop-type">'round'<br>&#124;&nbsp;'rounded'</span> | <span class="prop-default">'round'</span> | The shape of the pagination item. |
+| <span class="prop-name">size</span> | <span class="prop-type">'small'<br>&#124;&nbsp;'medium'<br>&#124;&nbsp;'large'</span> | <span class="prop-default">'medium'</span> | The size of the pagination item. |
+| <span class="prop-name">type</span> | <span class="prop-type">'page'<br>&#124;&nbsp;'first'<br>&#124;&nbsp;'last'<br>&#124;&nbsp;'next'<br>&#124;&nbsp;'previous'<br>&#124;&nbsp;'start-ellipsis'<br>&#124;&nbsp;'end-ellipsis'</span> | <span class="prop-default">'page'</span> |  |
+| <span class="prop-name">variant</span> | <span class="prop-type">'text'<br>&#124;&nbsp;'outlined'</span> |  |  |
+
+The `ref` is forwarded to the root element.
+
+Any other props supplied will be provided to the root element (native element).
+
+## CSS
+
+- Style sheet name: `PaginationItem`.
+- Style sheet details:
+
+| Rule name | Global class | Description |
+|:-----|:-------------|:------------|
+| <span class="prop-name">root</span> | <span class="prop-name">.root-44</span> | Styles applied to the root element.
+| <span class="prop-name">outlined</span> | <span class="prop-name">.outlined-45</span> | Styles applied to the button element if `outlined="true"`.
+| <span class="prop-name">textPrimary</span> | <span class="prop-name">.textPrimary-46</span> | Styles applied to the button element if `variant="text"` and `color="primary"`.
+| <span class="prop-name">textSecondary</span> | <span class="prop-name">.textSecondary-47</span> | Styles applied to the button element if `variant="text"` and `color="secondary"`.
+| <span class="prop-name">outlinedPrimary</span> | <span class="prop-name">.outlinedPrimary-48</span> | Styles applied to the button element if `variant="outlined"` and `color="primary"`.
+| <span class="prop-name">outlinedSecondary</span> | <span class="prop-name">.outlinedSecondary-49</span> | Styles applied to the button element if `variant="outlined"` and `color="secondary"`.
+| <span class="prop-name">rounded</span> | <span class="prop-name">.rounded-50</span> | Styles applied to the button element if `rounded="true"`.
+| <span class="prop-name">ellipsis</span> | <span class="prop-name">.ellipsis-51</span> | Styles applied to the ellipsis element.
+| <span class="prop-name">icon</span> | <span class="prop-name">.icon-52</span> | Styles applied to the icon element.
+| <span class="prop-name">sizeSmall</span> | <span class="prop-name">.sizeSmall-53</span> | Pseudo-class applied to the root element if `size="small"`.
+| <span class="prop-name">sizeLarge</span> | <span class="prop-name">.sizeLarge-54</span> | Pseudo-class applied to the root element if `size="large"`.
+| <span class="prop-name">disabled</span> | <span class="prop-name">.disabled-55</span> | Pseudo-class applied to the root element if `disabled={true}`.
+| <span class="prop-name">selected</span> | <span class="prop-name">.selected-56</span> | Pseudo-class applied to the root element if `selected={true}`.
+
+You can override the style of the component thanks to one of these customization points:
+
+- With a rule name of the [`classes` object prop](/customization/components/#overriding-styles-with-classes).
+- With a [global class name](/customization/components/#overriding-styles-with-global-class-names).
+- With a theme and an [`overrides` property](/customization/globals/#css).
+
+If that's not sufficient, you can check the [implementation of the component](https://github.com/mui-org/material-ui/blob/master/packages/material-ui-lab/src/PaginationItem/PaginationItem.js) for more detail.
+
+## Demos
+
+- [Pagination](/components/pagination/)
+

docs/pages/api/pagination.js

@@ -0,0 +1,7 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import markdown from './pagination.md';
+
+export default function Page() {
+  return <MarkdownDocs markdown={markdown} />;
+}

docs/pages/api/pagination.md

@@ -0,0 +1,71 @@
+---
+filename: /packages/material-ui-lab/src/Pagination/Pagination.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# Pagination API
+
+<p class="description">The API documentation of the Pagination React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import Pagination from '@material-ui/lab/Pagination';
+// or
+import { Pagination } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name">boundaryCount</span> | <span class="prop-type">number</span> |  | Number of always visible pages at the beginning and end. |
+| <span class="prop-name">children</span> | <span class="prop-type">node</span> |  | Pagination items. |
+| <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
+| <span class="prop-name">color</span> | <span class="prop-type">'default'<br>&#124;&nbsp;'primary'<br>&#124;&nbsp;'secondary'</span> |  | The active color. |
+| <span class="prop-name">count</span> | <span class="prop-type">number</span> |  | The total number of pages. |
+| <span class="prop-name">defaultPage</span> | <span class="prop-type">number</span> |  | The page selected by default when the component is uncontrolled. |
+| <span class="prop-name">disabled</span> | <span class="prop-type">bool</span> |  | If `true`, all the pagination component will be disabled. |
+| <span class="prop-name">getItemAriaLabel</span> | <span class="prop-type">func</span> |  | Accepts a function which returns a string value that provides a user-friendly name for the current page.<br><br>**Signature:**<br>`function(type?: string, page: number, selected: bool) => string`<br>*type:* The link or button type to format ('page' | 'first' | 'last' | 'next' | 'previous').<br>*page:* The page number to format.<br>*selected:* If true, the current page is selected. |
+| <span class="prop-name">hideNextButton</span> | <span class="prop-type">bool</span> |  | If `true`, hide the next-page button. |
+| <span class="prop-name">hidePrevButton</span> | <span class="prop-type">bool</span> |  | If `true`, hide the previous-page button. |
+| <span class="prop-name">onChange</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">page</span> | <span class="prop-type">number</span> |  | The current page. |
+| <span class="prop-name">renderItem</span> | <span class="prop-type">func</span> |  | Render the item.<br><br>**Signature:**<br>`function(params: object) => ReactNode`<br>*params:* null |
+| <span class="prop-name">shape</span> | <span class="prop-type">'round'<br>&#124;&nbsp;'rounded'</span> |  | The shape of the pagination items. |
+| <span class="prop-name">showFirstButton</span> | <span class="prop-type">bool</span> |  | If `true`, show the first-page button. |
+| <span class="prop-name">showLastButton</span> | <span class="prop-type">bool</span> |  | If `true`, show the last-page button. |
+| <span class="prop-name">siblingRange</span> | <span class="prop-type">number</span> |  | Number of always visible pages before and after the current page. |
+| <span class="prop-name">size</span> | <span class="prop-type">'small'<br>&#124;&nbsp;'medium'<br>&#124;&nbsp;'large'</span> |  | The size of the pagination component. |
+| <span class="prop-name">variant</span> | <span class="prop-type">'text'<br>&#124;&nbsp;'outlined'</span> |  | The variant to use. |
+
+The `ref` is forwarded to the root element.
+
+Any other props supplied will be provided to the root element (native element).
+
+## CSS
+
+- Style sheet name: `MuiPagination`.
+- Style sheet details:
+
+| Rule name | Global class | Description |
+|:-----|:-------------|:------------|
+| <span class="prop-name">root</span> | <span class="prop-name">.MuiPagination-root</span> | Styles applied to the root element.
+
+You can override the style of the component thanks to one of these customization points:
+
+- With a rule name of the [`classes` object prop](/customization/components/#overriding-styles-with-classes).
+- With a [global class name](/customization/components/#overriding-styles-with-global-class-names).
+- With a theme and an [`overrides` property](/customization/globals/#css).
+
+If that's not sufficient, you can check the [implementation of the component](https://github.com/mui-org/material-ui/blob/master/packages/material-ui-lab/src/Pagination/Pagination.js) for more detail.
+
+## Demos
+
+- [Pagination](/components/pagination/)
+

docs/pages/components/pagination.js

@@ -0,0 +1,14 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+
+const req = require.context('docs/src/pages/components/pagination', false, /\.(md|js|tsx)$/);
+const reqSource = require.context(
+  '!raw-loader!../../src/pages/components/pagination',
+  false,
+  /\.(js|tsx)$/,
+);
+const reqPrefix = 'pages/components/pagination';
+
+export default function Page() {
+  return <MarkdownDocs req={req} reqSource={reqSource} reqPrefix={reqPrefix} />;
+}

docs/src/pages.js

@@ -118,6 +118,7 @@ const pages = [
           { pathname: '/components/about-the-lab' },
           { pathname: '/components/alert' },
           { pathname: '/components/autocomplete' },
+          { pathname: '/components/pagination' },
           { pathname: '/components/rating' },
           { pathname: '/components/skeleton' },
           { pathname: '/components/speed-dial' },

docs/src/pages/components/pagination/BasicPagination.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Pagination from '@material-ui/lab/Pagination';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    '& > *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function BasicPagination() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Pagination count={10} />
+      <Pagination count={10} color="primary" />
+      <Pagination count={10} color="secondary" />
+      <Pagination count={10} disabled />
+    </div>
+  );
+}

docs/src/pages/components/pagination/PaginationButtons.js

@@ -0,0 +1,22 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Pagination from '@material-ui/lab/Pagination';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    '& > *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function PaginationButtons() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Pagination count={10} showFirstButton showLastButton />
+      <Pagination count={10} hidePrevButton hideNextButton />
+    </div>
+  );
+}

docs/src/pages/components/pagination/PaginationControlled.js

@@ -0,0 +1,25 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Typography from '@material-ui/core/Typography';
+import Pagination from '@material-ui/lab/Pagination';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    '& > *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function PaginationControlled() {
+  const classes = useStyles();
+  const [page, setPage] = React.useState(1);
+  const handleChange = (event, value) => setPage(value);
+
+  return (
+    <div className={classes.root}>
+      <Pagination count={10} page={page} onChange={handleChange} />
+      <Typography>Page: {page}</Typography>
+    </div>
+  );
+}

docs/src/pages/components/pagination/PaginationLink.js

@@ -0,0 +1,22 @@
+import React from 'react';
+import { MemoryRouter as Router } from 'react-router';
+import { Link } from 'react-router-dom';
+import Pagination from '@material-ui/lab/Pagination';
+import PaginationItem from '@material-ui/lab/PaginationItem';
+
+export default function PaginationLink() {
+  return (
+    <Router>
+      <Pagination
+        count={10}
+        renderItem={item => (
+          <PaginationItem
+            component={Link}
+            to={`/cars${item.page === 1 ? '' : `?page=${item.page}`}`}
+            {...item}
+          />
+        )}
+      />
+    </Router>
+  );
+}

docs/src/pages/components/pagination/PaginationLinkChildren.js

@@ -0,0 +1,27 @@
+import React from 'react';
+import { MemoryRouter as Router } from 'react-router';
+import { Link } from 'react-router-dom';
+import Pagination, { usePagination } from '@material-ui/lab/Pagination';
+import PaginationItem from '@material-ui/lab/PaginationItem';
+
+export default function PaginationLinkChildren() {
+  const { items } = usePagination({
+    count: 10,
+  });
+
+  return (
+    <Router>
+      <Pagination>
+        {items.map(item => (
+          <li key={item.type || item.page.toString()}>
+            <PaginationItem
+              component={Link}
+              to={`/cars${item.page === 1 ? '' : `?page=${item.page}`}`}
+              {...item}
+            />
+          </li>
+        ))}
+      </Pagination>
+    </Router>
+  );
+}

docs/src/pages/components/pagination/PaginationOutlined.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Pagination from '@material-ui/lab/Pagination';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    '& > *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function PaginationOutlined() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Pagination count={10} variant="outlined" />
+      <Pagination count={10} variant="outlined" color="primary" />
+      <Pagination count={10} variant="outlined" color="secondary" />
+      <Pagination count={10} variant="outlined" disabled />
+    </div>
+  );
+}

docs/src/pages/components/pagination/PaginationRanges.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Pagination from '@material-ui/lab/Pagination';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    '& > *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function PaginationRanges() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Pagination count={11} defaultPage={6} siblingCount={0} />
+      <Pagination count={11} defaultPage={6} /> {/* Default ranges */}
+      <Pagination count={11} defaultPage={6} siblingCount={0} boundaryCount={2} />
+      <Pagination count={11} defaultPage={6} boundaryCount={2} />
+    </div>
+  );
+}

docs/src/pages/components/pagination/PaginationRounded.js

@@ -0,0 +1,22 @@
+import React from 'react';
+import { makeStyles } from '@material-ui/core/styles';
+import Pagination from '@material-ui/lab/Pagination';
+
+const useStyles = makeStyles(theme => ({
+  root: {
+    '& > *': {
+      marginTop: theme.spacing(2),
+    },
+  },
+}));
+
+export default function PaginationRounded() {
+  const classes = useStyles();
+
+  return (
+    <div className={classes.root}>
+      <Pagination count={10} shape="rounded" />
+      <Pagination count={10} variant="outlined" shape="rounded" />
+    </div>
+  );
+}