Introduce pagination prop to tables and lists

.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

@@ -3929,3 +3929,116 @@ export function WithSubHeaders() {
     </LegacyCard>
   );
 }
+
+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>
+  );
+}

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';
@@ -88,6 +90,8 @@ interface IndexTableSortToggleLabels {
   [key: number]: IndexTableSortToggleLabel;
 }
 
+export type IndexTablePaginationProps = Omit<PaginationProps, 'type'>;
+
 export interface IndexTableBaseProps {
   headings: NonEmptyArray<IndexTableHeading>;
   promotedBulkActions?: BulkActionsProps['promotedActions'];
@@ -118,6 +122,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 {
@@ -1162,21 +1168,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,8 +24,10 @@
   }
 
   &.table {
+    border-top: 1px solid var(--p-color-border);
+
     button {
-      --button-min-height: var(--p-space-600);
+      --button-min-height: 28px;
       background-color: var(--p-color-bg-subdued);
       min-height: var(--button-min-height);
       min-width: var(--button-min-height);

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

@@ -64,7 +64,6 @@ export function WithTableType() {
       style={{
         maxWidth: 'calc(700px + (2 * var(--p-space-400)))',
         margin: '0 auto',
-        border: '1px solid var(--p-color-border)',
       }}
     >
       <Pagination