Update Pagination component (Workday#954)

* feat(pagination): Update Pagination component
Co-authored-by: Nicholas Boll <nicholas.boll@gmail.com>

modules/_labs/pagination/react/MIGRATION_GUIDE.md

@@ -0,0 +1,107 @@
+# Migration Guide
+
+## Deprecated API
+
+Below is a table of props in < v4.5 and notes about how they relate to the current API.
+
+| Name                           | Required in < v4.5? | New Name       | Notes                                                                                         |
+| ------------------------------ | ------------------- | -------------- | --------------------------------------------------------------------------------------------- |
+| `pageSize`                     | ✅ `true`           | n/a            | This is not needed in the new Pagination API                                                  |
+| `total`                        | ✅ `true`           | n/a            | This is not needed in the new Pagination API                                                  |
+| `currentPage`                  | ✅ `true`           | n/a            | This is not needed in the new Pagination API (though you can provide an `initialCurrentPage`) |
+| `onPageChange`                 | ✅ `true`           | `onPageChange` | This is now an optional prop in the new Pagination API                                        |
+| `showLabel`                    | 🚫 `false`          | n/a            | You can now access the label directly with the `AdditionalDetails` component                  |
+| `customLabel`                  | 🚫 `false`          | n/a            | You can now access the label directly with the `AdditionalDetails` component                  |
+| `showGoTo`                     | 🚫 `false`          | n/a            | You can now access the `GoToForm` component directly                                          |
+| `goToLabel`                    | 🚫 `false`          | n/a            | You can now access the label directly with the `GoToLabel` component                          |
+| `paginationContainerAriaLabel` | 🚫 `false`          | n/a            | You can now access the Pagination container directly                                          |
+| `previousPageAriaLabel`        | 🚫 `false`          | n/a            | You can now access the `StepToPrevious` button directly                                       |
+| `nextPageAriaLabel`            | 🚫 `false`          | n/a            | You can now access the `StepToNext` button directly                                           |
+| `pageButtonAriaLabel`          | 🚫 `false`          | n/a            | You can now access the `PageButton`s directly                                                 |
+
+## Example
+
+If you were previously writing your `Pagination component like this:
+
+```tsx
+import * as React from 'react';
+import Pagination from '@workday/canvas-kit-labs-react-pagination';
+
+const [currentPage, setCurrentPage] = React.useState(1);
+
+const MyPaginationComponent = () => {
+  return (
+    <Pagination
+      total={100}
+      pageSize={10}
+      currentPage={currentPage}
+      onPageChange={pageNumber => setCurrentPage(pageNumber)}
+      showLabel
+      showGoTo
+      dataLabel="candidate"
+    />
+  );
+};
+```
+
+You would now write something like this:
+
+```tsx
+import * as React from 'react';
+import {
+  Pagination,
+  getLastPage,
+  getVisibleResultsMin,
+  getVisibleResultsMax,
+} from '@workday/canvas-kit-labs-react-pagination';
+
+const MyPaginationComponent = () => {
+  //  In this example, Pagination state is handled internally,
+  // but this is added here to simplify the example
+  const [currentPage, setCurrentPage] = React.useState(1);
+  const resultsPerPage = 10;
+  const totalCount = 108;
+  const lastPage = getLastPage(resultCount, totalCount);
+
+  return (
+    <Pagination
+      aria-label="Pagination"
+      initialCurrentPage={currentPage}
+      lastPage={lastPage}
+      onPageChange={pageNumber => setCurrentPage(pageNumber)}
+    >
+      <Pagination.Controls>
+        <Pagination.JumpToFirstButton aria-label="First" />
+        <Pagination.StepToPreviousButton aria-label="Previous" />
+        <Pagination.PageList>
+          {({state}) =>
+            state.range.map(pageNumber => (
+              <Pagination.PageListItem key={pageNumber}>
+                <Pagination.PageButton aria-label={`Page ${pageNumber}`} pageNumber={pageNumber} />
+              </Pagination.PageListItem>
+            ))
+          }
+        </Pagination.PageList>
+        <Pagination.StepToNextButton aria-label="Next" />
+        <Pagination.JumpToLastButton aria-label="Last" />
+        <Pagination.GoToForm>
+          <Pagination.GoToTextInput aria-label="Go to page number" />
+          <Pagination.GoToLabel>{`of ${totalCount} candidates`}</Pagination.GoToLabel>
+        </Pagination.GoToForm>
+      </Pagination.Controls>
+      <Pagination.AdditionalDetails>
+        {({state}) =>
+          `${getVisibleResultsMin(state.currentPage, resultCount)}-${getVisibleResultsMax(
+            state.currentPage,
+            resultCount,
+            totalCount
+          )} of ${totalCount} candidates`
+        }
+      </Pagination.AdditionalDetails>
+    </Pagination>
+  );
+};
+```
+
+For more detailed information on this component, please refer to the
+[storybook documentation](https://workday.github.io/canvas-kit/?path=/docs/labs-pagination-react--step-controls)

modules/_labs/pagination/react/README.md

@@ -1,95 +1,12 @@
 # Canvas Kit React Pagination
 
+If you're upgrading from < v4.5, please refer to the [migration guide](MIGRATION_GUIDE.md).
+
 <a href="https://github.com/Workday/canvas-kit/tree/master/modules/_labs/README.md">
   <img src="https://img.shields.io/badge/LABS-beta-orange" alt="LABS: Beta" />
 </a>  This component is work in progress and currently in pre-release.
 
-Contains a component for a pagination bar and dispatches for page changes
-
-## Installation
-
-```sh
-yarn add @workday/canvas-kit-labs-react-pagination
-```
-
-## Usage
-
-```tsx
-import * as React from 'react';
-import Pagination from '@workday/canvas-kit-labs-react-pagination';
-
-const [currentPage, setCurrentPage] = React.useState(1);
-
-return (
-  <Pagination
-    total={100}
-    pageSize={10}
-    currentPage={currentPage}
-    onPageChange={p => setCurrentPage(p)}
-    showLabel
-    showGoTo
-    dataLabel="candidate"
-  />
-);
-```
-
-## Static Properties
-
-> None
-
-## 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.
-
-#### goToLabel?: string
-
-> Determines the label next to the Go To box. Defaults to 'Go To'. Only usable while showGoTo is set
-> to true.
-
-#### customLabel?: (from: number, to: number, items: number, itemLabel: string) => string
-
-> A function to build a custom label below the pagination bar.
-
-#### paginationContainerAriaLabel?: string;
-
-> Customizes the aria label for the Pagination container div. Default is 'Pagination'.
-
-#### previousPageAriaLabel?: string;
-
-> Customizes the aria label for the Previous Page Arrow. Default is 'Previous Page'.
-
-#### nextPageAriaLabel?: string;
-
-> Customizes the aria label for the Next Page Arrow. Default is 'Next Page'.
-
-#### pageButtonAriaLabel?: (page: number, selected: boolean) => string;
+`Pagination` is a compound component for handling navigation between pages in a range.
 
-> Customizes each page button. Default is (page: number, selected: boolean) =>
-> `${selected ? 'Selected, ' : ''}Page ${page}`
+For more detailed information on this component, please refer to the
+[storybook documentation](https://workday.github.io/canvas-kit/?path=/docs/labs-pagination-react--step-controls)

modules/_labs/pagination/react/index.ts

@@ -1,5 +1 @@
-import Pagination from './lib/Pagination';
-
-export default Pagination;
-export {Pagination};
 export * from './lib/Pagination';