Introduce pagination prop to tables and lists (#10633)

Supports Shopify/web#102860

`Pagination` is added as an auxiliary component to `DataTable`,
`IndexTable`, and `ResourceList`. This has resulted in inconsistent
usage and UX across Admin along with differing implementations. Baking
this concern into the resources will provide a consistent aesthetic and
ease our maintainability of pagination concerns with regards to these
components.

At the moment, `web` (i.e. Admin) has the following instance counts with
`Pagination`:
- DataTable - 8
- IndexTable - 34
- ResourceList - 25

There also includes 11 `ResourceListWithHeader` instances, but that is a
custom component within Admin. So, maintaining a consistent Pagination
experience across each of these instances becomes challenging if they
each need independent instantiation of `Pagination` as a child
component.

❓ For `IndexTable` should I key of
[hasMoreItems](https://github.com/Shopify/polaris/blob/557134c75c8f5b6dee0d925561e9a2b4ba900b2b/polaris-react/src/components/IndexTable/IndexTable.tsx#L1184)
to determine whether to render `Pagination` or should the consumer
manage it? Need to better understand what this attribute is used for and
whether that's reasonable. Edit: This does not seem to be consistently
used, so I don't think this would be reliable.

🚨 **REMINDER for myself:** Update documentation with regards to
`Pagination` and `IndexTable`

Introduces an optional `pagination` prop to `DataTable`, `IndexTable`,
and `ResourceList`. If the `pagination` prop is provided, which contains
the `Pagination` props, then it will render a table type `Pagination`
component at the bottom of the of the table/list. If no `pagination`
prop is provided, then it will not render a `Pagination` component.

The table type `Pagination` component will also have a border top by
default. We do not have a use case at the moment where a table type
`Pagination` component does not need this aesthetic, so it is always
present.

Increases table type `Pagination` buttons to a larger click area (i.e.
`28px`).

-
[Pagination](https://storybook.web.polaris-table-component-pagination.matt-kubej.us.spin.dev/?path=/story/all-components-pagination--with-table-type&globals=polarisSummerEditions2023:true;polarisSummerEditions2023ShadowBevelOptOut:true)
-
[DataTable](https://storybook.web.polaris-table-component-pagination.matt-kubej.us.spin.dev/?path=/story/all-components-datatable--with-pagination&globals=polarisSummerEditions2023:true;polarisSummerEditions2023ShadowBevelOptOut:true)
-
[IndexTable](https://storybook.web.polaris-table-component-pagination.matt-kubej.us.spin.dev/?path=/story/all-components-indextable--with-pagination&globals=polarisSummerEditions2023:true;polarisSummerEditions2023ShadowBevelOptOut:true)
-
[ResourceList](https://storybook.web.polaris-table-component-pagination.matt-kubej.us.spin.dev/?path=/story/all-components-resourcelist--with-pagination&globals=polarisSummerEditions2023:true;polarisSummerEditions2023ShadowBevelOptOut:true)

- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [ ] Tested on [multiple
browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers)
- [ ] Tested for
[accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md)
- [ ] Updated the component's `README.md` with documentation changes
- [ ] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide

---------

Co-authored-by: Marc Thomas <marc.thomas@shopify.com>

Author: 2 people

.changeset/silver-wasps-greet.md

@@ -0,0 +1,5 @@
+---
+'@shopify/polaris': minor
+---
+
+Updated IndexTable, ResourceList, and DataTable to have built-in pagination props

polaris-react/src/components/DataTable/DataTable.stories.tsx

@@ -874,3 +874,46 @@ export function WithStickyHeaderEnabled() {
     </Page>
   );
 }
+
+export function WithPagination() {
+  const rows = [
+    ['Emerald Silk Gown', '$875.00', 124689, 140, '$122,500.00'],
+    ['Mauve Cashmere Scarf', '$230.00', 124533, 83, '$19,090.00'],
+    [
+      'Navy Merino Wool Blazer with khaki chinos and yellow belt',
+      '$445.00',
+      124518,
+      32,
+      '$14,240.00',
+    ],
+  ];
+
+  return (
+    <Page title="Sales by product">
+      <LegacyCard>
+        <DataTable
+          columnContentTypes={[
+            'text',
+            'numeric',
+            'numeric',
+            'numeric',
+            'numeric',
+          ]}
+          headings={[
+            'Product',
+            'Price',
+            'SKU Number',
+            'Net quantity',
+            'Net sales',
+          ]}
+          rows={rows}
+          totals={['', '', '', 255, '$155,830.00']}
+          pagination={{
+            hasNext: true,
+            onNext: () => {},
+          }}
+        />
+      </LegacyCard>
+    </Page>
+  );
+}

polaris-react/src/components/DataTable/DataTable.tsx

@@ -10,6 +10,8 @@ import {headerCell} from '../shared';
 import {EventListener} from '../EventListener';
 import {AfterInitialMount} from '../AfterInitialMount';
 import {Sticky} from '../Sticky';
+import {Pagination} from '../Pagination';
+import type {PaginationProps} from '../Pagination';
 
 import {Cell, Navigation} from './components';
 import type {CellProps} from './components';
@@ -28,6 +30,8 @@ export type TableData = string | number | React.ReactNode;
 
 export type ColumnContentType = 'text' | 'numeric';
 
+export type DataTablePaginationProps = Omit<PaginationProps, 'type'>;
+
 const getRowClientHeights = (rows: NodeList | undefined) => {
   const heights: number[] = [];
   if (!rows) {
@@ -97,6 +101,8 @@ export interface DataTableProps {
   fixedFirstColumns?: number;
   /** Specify a min width for the first column if neccessary */
   firstColumnMinWidth?: string;
+  /** Properties to enable pagination at the bottom of the table. */
+  pagination?: DataTablePaginationProps;
 }
 
 type CombinedProps = DataTableProps & {
@@ -177,6 +183,7 @@ class DataTableInner extends PureComponent<CombinedProps, DataTableState> {
       hasZebraStripingOnData = false,
       stickyHeader = false,
       hasFixedFirstColumn: fixedFirstColumn = false,
+      pagination,
     } = this.props;
     const {
       condensed,
@@ -300,6 +307,10 @@ class DataTableInner extends PureComponent<CombinedProps, DataTableState> {
       <div className={styles.Footer}>{footerContent}</div>
     ) : null;
 
+    const paginationMarkup = pagination ? (
+      <Pagination type="table" {...pagination} />
+    ) : null;
+
     const headerTotalsMarkup = !showTotalsInFooter ? totalsMarkup : null;
     const footerTotalsMarkup = showTotalsInFooter ? (
       <tfoot>{totalsMarkup}</tfoot>
@@ -398,6 +409,7 @@ class DataTableInner extends PureComponent<CombinedProps, DataTableState> {
               {footerTotalsMarkup}
             </table>
           </div>
+          {paginationMarkup}
           {footerMarkup}
         </div>
       </div>

polaris-react/src/components/DataTable/tests/DataTable.test.tsx

@@ -3,6 +3,7 @@ import {timer} from '@shopify/jest-dom-mocks';
 import {mountWithApp} from 'tests/utilities';
 
 import {Checkbox} from '../../Checkbox';
+import {Pagination} from '../../Pagination';
 import {Cell, Navigation} from '../components';
 import {DataTable} from '../DataTable';
 import type {DataTableProps} from '../DataTable';
@@ -639,4 +640,27 @@ describe('<DataTable />', () => {
       expect(tables).toHaveLength(1);
     });
   });
+
+  describe('pagination', () => {
+    it('does not render Pagination when pagination props are not provided', () => {
+      const dataTable = mountWithApp(<DataTable {...defaultProps} />);
+
+      expect(dataTable).not.toContainReactComponent(Pagination);
+    });
+
+    it('renders Pagination with table type when pagination props are provided', () => {
+      const paginationProps = {
+        hasNext: true,
+      };
+
+      const dataTable = mountWithApp(
+        <DataTable {...defaultProps} pagination={paginationProps} />,
+      );
+
+      expect(dataTable).toContainReactComponent(Pagination, {
+        type: 'table',
+        ...paginationProps,
+      });
+    });
+  });
 });

polaris-react/src/components/IndexTable/IndexTable.stories.tsx

@@ -1799,7 +1799,6 @@ export function WithStickyLastColumn() {
             {amountSpent}
           </Text>
         </IndexTable.Cell>
-        <IndexTable.Cell>{status}</IndexTable.Cell>
         <IndexTable.Cell>{channel}</IndexTable.Cell>
         <IndexTable.Cell>{paymentStatus}</IndexTable.Cell>
         <IndexTable.Cell>{fulfillmentStatus}</IndexTable.Cell>
@@ -1829,7 +1828,6 @@ export function WithStickyLastColumn() {
             id: 'amount-spent',
             title: 'Amount spent',
           },
-          {title: 'Tone'},
           {title: 'Channel'},
           {title: 'Payment status'},
           {title: 'Fulfillment status'},
@@ -4003,6 +4001,119 @@ export function WithSubHeaders() {
   );
 }
 
+export function WithPagination() {
+  const customers = [
+    {
+      id: '3410',
+      url: '#',
+      name: 'Mae Jemison',
+      location: 'Decatur, USA',
+      orders: 20,
+      amountSpent: '$2,400',
+    },
+    {
+      id: '3411',
+      url: '#',
+      name: 'Joe Jemison',
+      location: 'Sydney, AU',
+      orders: 20,
+      amountSpent: '$1,400',
+    },
+    {
+      id: '3412',
+      url: '#',
+      name: 'Sam Jemison',
+      location: 'Decatur, USA',
+      orders: 20,
+      amountSpent: '$400',
+    },
+    {
+      id: '3413',
+      url: '#',
+      name: 'Mae Jemison',
+      location: 'Decatur, USA',
+      orders: 20,
+      amountSpent: '$4,300',
+    },
+    {
+      id: '2563',
+      url: '#',
+      name: 'Ellen Ochoa',
+      location: 'Los Angeles, USA',
+      orders: 30,
+      amountSpent: '$140',
+    },
+  ];
+  const resourceName = {
+    singular: 'customer',
+    plural: 'customers',
+  };
+
+  const {selectedResources, allResourcesSelected, handleSelectionChange} =
+    useIndexResourceState(customers);
+
+  const rowMarkup = customers.map(
+    ({id, name, location, orders, amountSpent}, index) => (
+      <IndexTable.Row
+        id={id}
+        key={id}
+        selected={selectedResources.includes(id)}
+        position={index}
+      >
+        <IndexTable.Cell>
+          <Text fontWeight="bold" as="span">
+            {name}
+          </Text>
+        </IndexTable.Cell>
+        <IndexTable.Cell>{location}</IndexTable.Cell>
+        <IndexTable.Cell>
+          <Text as="span" alignment="end" numeric>
+            {orders}
+          </Text>
+        </IndexTable.Cell>
+        <IndexTable.Cell>
+          <Text as="span" alignment="end" numeric>
+            {amountSpent}
+          </Text>
+        </IndexTable.Cell>
+      </IndexTable.Row>
+    ),
+  );
+
+  return (
+    <LegacyCard>
+      <IndexTable
+        resourceName={resourceName}
+        itemCount={customers.length}
+        selectedItemsCount={
+          allResourcesSelected ? 'All' : selectedResources.length
+        }
+        onSelectionChange={handleSelectionChange}
+        headings={[
+          {title: 'Name'},
+          {title: 'Location'},
+          {
+            alignment: 'end',
+            id: 'order-count',
+            title: 'Order count',
+          },
+          {
+            alignment: 'end',
+            id: 'amount-spent',
+            title: 'Amount spent',
+          },
+        ]}
+        pagination={{
+          hasNext: true,
+          onNext: () => {},
+        }}
+      >
+        {rowMarkup}
+      </IndexTable>
+    </LegacyCard>
+  );
+}
+
 export function WithSubHeadersNonSelectable() {
   const rows = [
     {

polaris-react/src/components/IndexTable/IndexTable.tsx

@@ -15,6 +15,8 @@ import {EventListener} from '../EventListener';
 import {SelectAllActions} from '../SelectAllActions';
 // eslint-disable-next-line import/no-deprecated
 import {LegacyStack} from '../LegacyStack';
+import {Pagination} from '../Pagination';
+import type {PaginationProps} from '../Pagination';
 import {Sticky} from '../Sticky';
 import {Spinner} from '../Spinner';
 import {Text} from '../Text';
@@ -89,6 +91,8 @@ interface IndexTableSortToggleLabels {
   [key: number]: IndexTableSortToggleLabel;
 }
 
+export type IndexTablePaginationProps = Omit<PaginationProps, 'type'>;
+
 export interface IndexTableBaseProps {
   headings: NonEmptyArray<IndexTableHeading>;
   promotedBulkActions?: BulkActionsProps['promotedActions'];
@@ -119,6 +123,8 @@ export interface IndexTableBaseProps {
   sortToggleLabels?: IndexTableSortToggleLabels;
   /** Add zebra striping to table rows */
   hasZebraStriping?: boolean;
+  /** Properties to enable pagination at the bottom of the table. */
+  pagination?: IndexTablePaginationProps;
 }
 
 export interface TableHeadingRect {
@@ -1165,21 +1171,29 @@ export function IndexTable({
   hasMoreItems,
   condensed,
   onSelectionChange,
+  pagination,
   ...indexTableBaseProps
 }: IndexTableProps) {
+  const paginationMarkup = pagination ? (
+    <Pagination type="table" {...pagination} />
+  ) : null;
+
   return (
-    <IndexProvider
-      selectable={selectable && !condensed}
-      itemCount={itemCount}
-      selectedItemsCount={selectedItemsCount}
-      resourceName={passedResourceName}
-      loading={loading}
-      hasMoreItems={hasMoreItems}
-      condensed={condensed}
-      onSelectionChange={onSelectionChange}
-    >
-      <IndexTableBase {...indexTableBaseProps}>{children}</IndexTableBase>
-    </IndexProvider>
+    <>
+      <IndexProvider
+        selectable={selectable && !condensed}
+        itemCount={itemCount}
+        selectedItemsCount={selectedItemsCount}
+        resourceName={passedResourceName}
+        loading={loading}
+        hasMoreItems={hasMoreItems}
+        condensed={condensed}
+        onSelectionChange={onSelectionChange}
+      >
+        <IndexTableBase {...indexTableBaseProps}>{children}</IndexTableBase>
+      </IndexProvider>
+      {paginationMarkup}
+    </>
   );
 }
 

polaris-react/src/components/IndexTable/tests/IndexTable.test.tsx

@@ -22,6 +22,7 @@ import {AfterInitialMount} from '../../AfterInitialMount';
 import {UnstyledButton} from '../../UnstyledButton';
 import {Tooltip} from '../../Tooltip';
 import {IndexProvider} from '../../IndexProvider';
+import {Pagination} from '../../Pagination';
 
 jest.mock('../utilities', () => ({
   ...jest.requireActual('../utilities'),
@@ -802,4 +803,33 @@ describe('<IndexTable>', () => {
       expect(computeTableDimensions).toHaveBeenCalledTimes(2);
     });
   });
+
+  describe('pagination', () => {
+    it('does not render Pagination when pagination props are not provided', () => {
+      const index = mountWithApp(
+        <IndexTable {...defaultProps} pagination={undefined}>
+          {mockTableItems.map(mockRenderRow)}
+        </IndexTable>,
+      );
+
+      expect(index).not.toContainReactComponent(Pagination);
+    });
+
+    it('renders Pagination with table type when pagination props are provided', () => {
+      const paginationProps = {
+        hasNext: true,
+      };
+
+      const index = mountWithApp(
+        <IndexTable {...defaultProps} pagination={paginationProps}>
+          {mockTableItems.map(mockRenderRow)}
+        </IndexTable>,
+      );
+
+      expect(index).toContainReactComponent(Pagination, {
+        type: 'table',
+        ...paginationProps,
+      });
+    });
+  });
 });

polaris-react/src/components/Pagination/Pagination.scss

@@ -24,6 +24,8 @@
   }
 
   &.table {
+    border-top: 1px solid var(--p-color-border);
+
     button {
       --button-min-height: var(--p-space-600);
       background-color: var(--p-color-bg-surface-secondary);