[Pagination] Add new component

[webuxmotion]

We need the new Pagination component like this https://react.semantic-ui.com/addons/pagination/

[oliviertassinari]

Related to szmslab/material-ui-flat-pagination#12 (comment)

[iRyanBell]

How about something like this? https://github.com/vim-labs/materialui-pagination-component

[oliviertassinari]

@iRyanBell Thanks for sharing. We will need to provide a built-in solution in Material-UI in the near future. I hope we can deliver it by Q1 2020. Would you be interested in this effort? I can guide you into this. I would need to run a benchmark in order to better understand how we can move forward. It would likely require a new effort, taking the good parts from everybody, your project included.

[iRyanBell]

@oliviertassinari Count me in.

[oliviertassinari]

@iRyanBell Awesome, I will try to quick that off tomorrow.

[TrejGun]

in case you are interested. this lib is used by react-bootsrap

https://github.com/ultimate-pagination/react-ultimate-pagination

[oliviertassinari]

Benchmark

I have used the following sources to benchmark:

• https://a11y-style-guide.com/style-guide/section-navigation.html#kssref-navigation-pagination
• https://www.a11ymatters.com/pattern/pagination/
• https://getbootstrap.com/docs/4.3/components/pagination/#disabled-and-active-states
• https://ant.design/components/pagination/#header
• https://elastic.github.io/eui/#/navigation/pagination
• https://garden.zendesk.com/react-components/pagination/
• https://www.carbondesignsystem.com/components/pagination/code
• https://element.eleme.io/#/en-US/component/pagination#pagination
• https://react-bootstrap.netlify.com/components/pagination/#pagination
• https://react.semantic-ui.com/addons/pagination/
• https://quasar.dev/vue-components/pagination
• https://baseweb.design/components/pagination/
• https://kiwicom.github.io/orbit-components/?path=/story/pagination--default
• https://atlaskit.atlassian.com/packages/core/pagination#/
• https://vuetifyjs.com/en/components/paginations#paginations
• https://mdbootstrap.com/docs/jquery/components/pagination/
• https://bulma.io/documentation/components/pagination/
• https://rsuitejs.com/en/components/pagination
• https://opensource.adobe.com/spectrum-css/components/pagination-listing/#
• https://demos.creative-tim.com/bs3/material-dashboard-pro/examples/tables/datatables.net.html
• https://dribbble.com/tags/pagination
• https://github.com/vim-labs/materialui-pagination-component
• https://github.com/szmslab/material-ui-flat-pagination

Proposal

I would recommend the following:

1. I would propose this API

Pagination.propTypes = {
  /**
   * If `true`, all links  will be disabled.
   */
  disabled: PropTypes.bool,
  /**
   * The size.
   *
   * default 'medium'
   */
  size: PropTypes.oneOf(['small', 'medium']),
  /**
   * The active color.
   */
  color: PropTypes.oneOf(['primary', 'secondary']),
  /**
   * Callback fired when the page is changed.
   *
   * @param {object} event The event source of the callback.
   * @param {number} page The page selected.
   */
  onChange: PropTypes.func,
  /**
   * The zero-based index of the current page.
   */
  page: PropTypes.number.isRequired,
  /**
   * The total number of pages.
   */
  count: PropTypes.number.isRequired,
  /**
   * Number of always visible pages at the beginning and end.
   */
  boundaryRange: PropTypes.number,
  /**
   * Number of always visible pages before and after the current one.
   */
  siblingRange: PropTypes.number,
  /**
   * If `true`, show the first page item.
   */
  displayFirstItem: PropTypes.bool,
  /**
   * Render the item.
   *
   * @param {object} params
   * @returns {ReactNode}
   */
  renderItem: PropTypes.func,
  /**
   * Text label for the first page item.
   *
   * default First page
   */
  firstItemText: PropTypes.string,
  /**
   * Text label for the next page item.
   *
   * default Next page
   */
  nextItemText: PropTypes.string,
  /**
   * Text label for the next page item.
   *
   * default Last page
   */
  lastItemText: PropTypes.string,
  /**
   * Text label for the next page item.
   *
   * default Previous page
   */
  previousItemText: PropTypes.string,
  /**
   * If `true`, hide the next page item.
   */
  hideNextItem: PropTypes.bool,
  /**
   * If `true`, hide the previous page item.
   */
  hidePreviousItem: PropTypes.bool,
  /**
   * If `true`, show the last page item.
   */
  displayLastItem: PropTypes.bool,
};

2. We translate the xText props.
3. Add integration demo with react-router.
4. Not to use the Paper component.
5. Render links, not buttons.
6. We might want to expose a PaginationItem component so people can compose it in the renderItem prop.
7. What about we only expose one style of the pagination?
8. Mentioning TablePagination in the documentation
9. Remove references to "material-ui-flat-pagination" from the documentation
10. Explore responsive support, e.g. Pagination is not responsive by default twbs/bootstrap#23504.

References

• React Router example: https://atlaskit.atlassian.com/packages/core/pagination#/)
• boundaryRange and siblingRange behavior example: https://react.semantic-ui.com/addons/pagination/#types-compact
• Variants ideas, I prefer the 1.

1. https://atlaskit.atlassian.com/packages/core/pagination#/about
   
2. https://github.com/vim-labs/materialui-pagination-component
   
3. https://dribbble.com/shots/6726286-DailyUI085-Pagination
   

[iRyanBell]

I'm surprised to see so few other examples using a select box for page selection. I found this to be very intuitive and the fastest way to move between specific pages.

Personally, disabled buttons with "..." feels a bit unnecessary, but it is a very common design trend. On Bing.com, they only use the ellipsis on the left edge.

[oliviertassinari]

I share the same observation. I have seen one select based pagination (baseui). An input field seems more frequent. For instance https://www.shutterstock.com/fr/search/tree.

On Bing.com, they only use the ellipsis on the left edge.

Actually, I think that bondaryPageRange=0 should lead to no ellipses.

[oliviertassinari]

I had another thought, what if we expose the Pagination DOM structure. Something like this (1)?

import React from 'react';
import { Link } from '@material-ui/core';
import { Link as RouterLink } from 'react-router-dom';
import { usePagination, Pagination, PaginationItem } from '@material-ui/lab';

// The use of React.forwardRef will no longer be required for react-router-dom v6.
// See https://github.com/ReactTraining/react-router/issues/6056
const Link1 = React.forwardRef<HTMLAnchorElement, RouterLinkProps>((props, ref) => (
  <RouterLink innerRef={ref} {...props} />
));

function MyPagination() {
  const items = usePagination({
    page: 2,
    count: 10,
  });

  return (
    <Pagination>
      {items.map(item =>
        <PaginationItem
          to={`/cars${item.page === 1 ? '' : `?page=${item.page}`}`}
          component={Link1}
          {...item}
        />
      )}
    </Pagination>
  )
}

Instead of (2)

import React from 'react';
import { Link } from '@material-ui/core';
import { Link as RouterLink } from 'react-router-dom';
import { Pagination, PaginationItem } from '@material-ui/lab';

// The use of React.forwardRef will no longer be required for react-router-dom v6.
// See https://github.com/ReactTraining/react-router/issues/6056
const Link1 = React.forwardRef<HTMLAnchorElement, RouterLinkProps>((props, ref) => (
  <RouterLink innerRef={ref} {...props} />
));

function MyPagination() {
  return (
    <Pagination
      page={2}
      count={10}
      renderItem={(item => (
        <PaginationItem
          to={`/cars${item.page === 1 ? '' : `?page=${item.page}`}`}
          component={Link1}
          {...item}
        />
      )}
    />
  )
}

But maybe we can support both.