feat(pagination): add pagination bar component

[nikolastsakonas]

Summary

This PR includes a new pagination bar component. This can be used to manage paginated data in tables. The component includes a onPageChange prop/dispatch so that users can be notified of page changes. It also includes an optional GoTo box for navigating quickly between pages, and an optional customizable label below the pagination bar.

Files/Components

GoTo.tsx

Manages the Go To text input box adjacent to the Pagination Bar

Pages.tsx

Manages the pagination boxes for each page. Determines the range of numbers, as well as when to show ellipses for backward/forwards jumps.

Pagination.tsx

Manages the entire pagination bar. Renders the arrows, label, and Page/GoTo components.

Checklist

• branch has been rebased on the latest master commit
• tests are changed or added
• yarn test passes
• all (dev)dependencies that the module needs is added to its package.json
• code has been documented and, if applicable, usage described in README.md
• module has been added to canvas-kit-react and/or canvas-kit-css universal modules, if
  applicable
• design approved final implementation
• a11y approved final implementation
• code adheres to the API & Pattern guidelines

Additional References

Usage

import * as React from 'react';
import Pagination from '@workday/canvas-kit-react-pagination';

const [currentPage, setCurrentPage] = React.useState(1);

return (
    <Pagination
      total={100}
      pageSize={10}
      currentPage={currentPage}
      onPageChange={p => setCurrentPage(p)}
      showLabel
      showGoTo
      customLabel={(from: number, to: number, items: number, item: string) =>
          `${from.toLocaleString()} to ${to.toLocaleString()} of ${items.toLocaleString()} ${
            items > 1 ? 'companies' : 'company'
          }`
      }
    />
);

Component Props

Required

total: number

The total number of items

pageSize: number

The number of items to display per page

currentPage: number

The current page being displayed

onPageChange: (page: number) => void

Dispatch which is invoked when the page is changed

Optional

showLabel?: boolean

Shows a label below the pagination bar describing the items currently being viewed

showGoTo?: boolean

Shows a box adjacent to the pagination bar where a page can be entered and is submitted when
'Enter' key is pressed

customLabel?: (from: number, to: number, items: number, itemLabel: string) => string

A function to build a custom label below the pagination bar.

Screenshots

[NicholasBoll]

This looks similar to the work done in #282. @nikolasjchaconas would you mind collaborating with @lychyi on this change? I know @lychyi is collaborating with the Canvas UX team.

[lychyi]

This looks similar to the work done in #282. @nikolasjchaconas would you mind collaborating with @lychyi on this change? I know @lychyi is collaborating with the Canvas UX team.

This was something that @nikolasjchaconas talked about behind-the-scenes, let's carry on with the review of this PR. I've closed #282 to avoid any confusion.

We had also talked about reviewing this component's API first as a "first pass through" so that reviewers don't have to get too caught up in the code. #282 didn't have a design review of its API either so now is a great time to do it before we spend time churning on the finer details.

For next steps, I recommend that we ensure the component API, its props, and prescribed usage are spot on before diving any deeper into the codebase. @nikolasjchaconas Can you update the PR with the proposed props and an example usage so we can all agree on the API? Once that's good to go (maybe it's already been discussed as well) we can get moving on reviews or any other features that need to be worked on.

[nikolastsakonas]

@lychyi good point, I went ahead and updated my comment to include example usage and props 👍

[lychyi]

Some feedback on the API:

dataLabel?: string may benefit from being a formatter instead of a string: https://github.com/Workday/canvas-kit/pull/282/files#diff-70d947a4ff76cce616efca6cba576125R100-R113

That way the label string can be anything. It may be worth reaching out to the DS team to see if the language of this label has to be fixed. Either way, it has to be flexible because of localization so we may as well make it completely customizable.

[nikolastsakonas]

That way the label string can be anything. It may be worth reaching out to the DS team to see if the language of this label has to be fixed. Either way, it has to be flexible because of localization so we may as well make it completely customizable.

Makes sense, I'll go ahead and make this change

Edit: Made the change and replaced dataLabel with

customLabel?: (from: number, to: number, items: number, itemLabel: string) => string

A function to build a custom label below the pagination bar.

[NicholasBoll]

This update adds support for knobs

[NicholasBoll]

These stories no longer handle auto-resize by the browser. Perhaps we should use react-use to add functionality back? I think width should be provided for greater flexibility, but our stories should show how to pass it in.

[lychyi]

1912cd6#diff-6d9fd0b9c3ff083fe440fe499966caafR243

This is bothering the heck out of me. Having your builds be non-deterministic in this manner makes me nervous. Like it's a sign something is off but it's not pointing us in the right direction.

However, it shouldn't gate merging into Labs. We should get this branch updated and merge. 🎉

[NicholasBoll]

Yeah. I'm not happy with that diff. I wasn't able to figure it out. My editor didn't show an issue, but I could reproduce by running yarn build-storybook locally. So it wasn't just CI.

Perhaps upgrading Typescript would fix the issue? I gave up on trying to figure out why I was getting the error.