From ec5005e5b68f81848e952b3ed0350ca82217e86a Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Mon, 9 Sep 2019 10:43:04 -0400
Subject: [PATCH 01/14] Added label prop to Pagination

---
 src/components/Pagination/Pagination.scss     |  9 +++++++++
 src/components/Pagination/Pagination.tsx      | 19 +++++++++++++++----
 .../Pagination/tests/Pagination.test.tsx      |  8 ++++++++
 3 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/src/components/Pagination/Pagination.scss b/src/components/Pagination/Pagination.scss
index 0ab14501ea7..b7c5488eb82 100644
--- a/src/components/Pagination/Pagination.scss
+++ b/src/components/Pagination/Pagination.scss
@@ -8,6 +8,7 @@ $difference-between-touch-area-and-backdrop: control-height() -
 // This is the adjustment needed to get the icon to appear flush with other
 // content around it.
 $plain-horizontal-adjustment: spacing(tight);
+$labelMinWidth: rem(80px);
 
 $stacking-order: (
   item: 10,
@@ -108,6 +109,7 @@ $stacking-order: (
   );
   border: border(dark);
   border-radius: border-radius();
+
   line-height: 1;
   color: color('ink');
   text-align: center;
@@ -166,3 +168,10 @@ $stacking-order: (
   border-top-left-radius: 0;
   border-bottom-left-radius: 0;
 }
+
+.Label {
+  min-width: $labelMinWidth;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index f05239e0d04..7f5158991fe 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -1,5 +1,6 @@
 import React from 'react';
 import {ArrowLeftMinor, ArrowRightMinor} from '@shopify/polaris-icons';
+import {TextStyle} from '../TextStyle';
 import {classNames} from '../../utilities/css';
 import {useI18n} from '../../utilities/i18n';
 import {isInputFocused} from '../../utilities/is-input-focused';
@@ -35,6 +36,8 @@ export interface PaginationDescriptor {
   onNext?(): void;
   /** Callback when previous button is clicked */
   onPrevious?(): void;
+  /** Show page number information */
+  label?: string;
 }
 
 export interface PaginationProps extends PaginationDescriptor {
@@ -55,16 +58,17 @@ export function Pagination({
   previousKeys,
   plain,
   accessibilityLabel,
+  label,
 }: PaginationProps) {
   const intl = useI18n();
 
   const node: React.RefObject<HTMLElement> = React.createRef();
-  let label: string;
+  let navLabel: string;
 
   if (accessibilityLabel) {
-    label = accessibilityLabel;
+    navLabel = accessibilityLabel;
   } else {
-    label = intl.translate('Polaris.Pagination.pagination');
+    navLabel = intl.translate('Polaris.Pagination.pagination');
   }
 
   const className = classNames(styles.Pagination, plain && styles.plain);
@@ -163,10 +167,17 @@ export function Pagination({
       />
     ));
 
+  const labelMarkup = label ? (
+    <div className={styles.Label} aria-live="polite">
+      <TextStyle variation="subdued">{label}</TextStyle>
+    </div>
+  ) : null;
+
   return (
-    <nav className={className} aria-label={label} ref={node}>
+    <nav className={className} aria-label={navLabel} ref={node}>
       {previousButtonEvents}
       {constructedPrevious}
+      {labelMarkup}
       {nextButtonEvents}
       {constructedNext}
     </nav>
diff --git a/src/components/Pagination/tests/Pagination.test.tsx b/src/components/Pagination/tests/Pagination.test.tsx
index 75578ed0823..677ad5276ef 100644
--- a/src/components/Pagination/tests/Pagination.test.tsx
+++ b/src/components/Pagination/tests/Pagination.test.tsx
@@ -78,6 +78,14 @@ describe('<Pagination />', () => {
     });
   });
 
+  describe('label', () => {
+    it('renders as text', () => {
+      const label = 'test';
+      const pagination = mountWithAppProvider(<Pagination label={label} />);
+      expect(pagination.text()).toContain(label);
+    });
+  });
+
   it('adds a keypress event for nextKeys', () => {
     const spy = jest.fn();
     mountWithAppProvider(

From 2c9fea08f514602f507771881dc0369f33df95f8 Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 09:25:15 -0400
Subject: [PATCH 02/14] Updated padding of label prop to be more scalable

---
 src/components/Pagination/Pagination.scss | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/components/Pagination/Pagination.scss b/src/components/Pagination/Pagination.scss
index b7c5488eb82..707221e1e90 100644
--- a/src/components/Pagination/Pagination.scss
+++ b/src/components/Pagination/Pagination.scss
@@ -8,7 +8,6 @@ $difference-between-touch-area-and-backdrop: control-height() -
 // This is the adjustment needed to get the icon to appear flush with other
 // content around it.
 $plain-horizontal-adjustment: spacing(tight);
-$labelMinWidth: rem(80px);
 
 $stacking-order: (
   item: 10,
@@ -170,7 +169,7 @@ $stacking-order: (
 }
 
 .Label {
-  min-width: $labelMinWidth;
+  padding: 0 spacing(tight);
   display: flex;
   align-items: center;
   justify-content: center;

From ebe3d8389e546c826e021acdec1d929fb50633cb Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 09:29:04 -0400
Subject: [PATCH 03/14] Cleaned up conditional statement

---
 src/components/Pagination/Pagination.tsx | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index 7f5158991fe..398aee9188d 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -63,13 +63,10 @@ export function Pagination({
   const intl = useI18n();
 
   const node: React.RefObject<HTMLElement> = React.createRef();
-  let navLabel: string;
 
-  if (accessibilityLabel) {
-    navLabel = accessibilityLabel;
-  } else {
-    navLabel = intl.translate('Polaris.Pagination.pagination');
-  }
+  const navLabel = accessibilityLabel
+    ? accessibilityLabel
+    : intl.translate('Polaris.Pagination.pagination');
 
   const className = classNames(styles.Pagination, plain && styles.plain);
   const previousClassName = classNames(styles.Button, styles.PreviousButton);

From f72001ca8a0dd0807d69725680c91874826df8fe Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 09:33:48 -0400
Subject: [PATCH 04/14] Further tweaks

---
 src/components/Pagination/Pagination.tsx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index 398aee9188d..1999d6b4e0b 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -64,9 +64,8 @@ export function Pagination({
 
   const node: React.RefObject<HTMLElement> = React.createRef();
 
-  const navLabel = accessibilityLabel
-    ? accessibilityLabel
-    : intl.translate('Polaris.Pagination.pagination');
+  const navLabel =
+    accessibilityLabel || intl.translate('Polaris.Pagination.pagination');
 
   const className = classNames(styles.Pagination, plain && styles.plain);
   const previousClassName = classNames(styles.Button, styles.PreviousButton);

From 3e7a9a0dc0de9df9e37d8c04969aaa7fbe92b1ad Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 09:41:12 -0400
Subject: [PATCH 05/14] Added new test for existing a11y label prop

---
 src/components/Pagination/tests/Pagination.test.tsx | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/components/Pagination/tests/Pagination.test.tsx b/src/components/Pagination/tests/Pagination.test.tsx
index 677ad5276ef..4a5f25d42be 100644
--- a/src/components/Pagination/tests/Pagination.test.tsx
+++ b/src/components/Pagination/tests/Pagination.test.tsx
@@ -78,6 +78,18 @@ describe('<Pagination />', () => {
     });
   });
 
+  describe('accessibilityLabel', () => {
+    it('inserts as an aria label', () => {
+      const accessibilityLabel = 'test';
+      const pagination = mountWithAppProvider(
+        <Pagination accessibilityLabel={accessibilityLabel} />,
+      );
+      expect(pagination.find('nav').prop('aria-label')).toStrictEqual(
+        accessibilityLabel,
+      );
+    });
+  });
+
   describe('label', () => {
     it('renders as text', () => {
       const label = 'test';

From dda9de8c48aaa4845dfb6fe59966be78140610ee Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 09:45:55 -0400
Subject: [PATCH 06/14] Added more test coverage for the a11y label

---
 src/components/Pagination/tests/Pagination.test.tsx | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/components/Pagination/tests/Pagination.test.tsx b/src/components/Pagination/tests/Pagination.test.tsx
index 4a5f25d42be..afbfbde82de 100644
--- a/src/components/Pagination/tests/Pagination.test.tsx
+++ b/src/components/Pagination/tests/Pagination.test.tsx
@@ -79,7 +79,7 @@ describe('<Pagination />', () => {
   });
 
   describe('accessibilityLabel', () => {
-    it('inserts as an aria label', () => {
+    it('inserts prop as aria-label', () => {
       const accessibilityLabel = 'test';
       const pagination = mountWithAppProvider(
         <Pagination accessibilityLabel={accessibilityLabel} />,
@@ -88,6 +88,13 @@ describe('<Pagination />', () => {
         accessibilityLabel,
       );
     });
+
+    it('uses default value for aria-label', () => {
+      const pagination = mountWithAppProvider(<Pagination />);
+      expect(pagination.find('nav').prop('aria-label')).toStrictEqual(
+        'Pagination',
+      );
+    });
   });
 
   describe('label', () => {

From cf7dc0d1bb4d7945302a317d0b54e7d75061b1e4 Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 09:55:59 -0400
Subject: [PATCH 07/14] added support to make pagination label subdued
 depending on a condition

---
 src/components/Pagination/Pagination.tsx | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index 1999d6b4e0b..75f8742d05c 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -163,9 +163,16 @@ export function Pagination({
       />
     ));
 
+  const labelTextMarkup =
+    hasNext && hasPrevious ? (
+      <TextStyle>{label}</TextStyle>
+    ) : (
+      <TextStyle variation="subdued">{label}</TextStyle>
+    );
+
   const labelMarkup = label ? (
     <div className={styles.Label} aria-live="polite">
-      <TextStyle variation="subdued">{label}</TextStyle>
+      {labelTextMarkup}
     </div>
   ) : null;
 

From 60a18072eac2f1af581d10a2f615e89a93423321 Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 10:01:06 -0400
Subject: [PATCH 08/14] Edited inaccurate prop comment

---
 src/components/Pagination/Pagination.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index 75f8742d05c..628d763fc2d 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -36,7 +36,7 @@ export interface PaginationDescriptor {
   onNext?(): void;
   /** Callback when previous button is clicked */
   onPrevious?(): void;
-  /** Show page number information */
+  /** Text to provide more context in between the arrow buttons */
   label?: string;
 }
 

From d80085c3c83de05595efe46e50bec793b8712873 Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 10:13:56 -0400
Subject: [PATCH 09/14] New styles for pagination buttons that have a label
 present

---
 src/components/Pagination/Pagination.scss |  4 ++++
 src/components/Pagination/Pagination.tsx  | 12 ++++++++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/components/Pagination/Pagination.scss b/src/components/Pagination/Pagination.scss
index 707221e1e90..28e7205a34a 100644
--- a/src/components/Pagination/Pagination.scss
+++ b/src/components/Pagination/Pagination.scss
@@ -168,6 +168,10 @@ $stacking-order: (
   border-bottom-left-radius: 0;
 }
 
+.ButtonWithLabel {
+  border-radius: border-radius();
+}
+
 .Label {
   padding: 0 spacing(tight);
   display: flex;
diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index 628d763fc2d..1d2af304812 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -68,8 +68,16 @@ export function Pagination({
     accessibilityLabel || intl.translate('Polaris.Pagination.pagination');
 
   const className = classNames(styles.Pagination, plain && styles.plain);
-  const previousClassName = classNames(styles.Button, styles.PreviousButton);
-  const nextClassName = classNames(styles.Button, styles.NextButton);
+  const previousClassName = classNames(
+    styles.Button,
+    styles.PreviousButton,
+    label && styles.ButtonWithLabel,
+  );
+  const nextClassName = classNames(
+    styles.Button,
+    styles.NextButton,
+    label && styles.ButtonWithLabel,
+  );
 
   const previousButton = previousURL ? (
     <UnstyledLink

From 1e4097f3552fdd0239ecb64d1633f72892719cd7 Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 15:43:50 -0400
Subject: [PATCH 10/14] Added new test to assert the subdued text

---
 src/components/Pagination/tests/Pagination.test.tsx | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/components/Pagination/tests/Pagination.test.tsx b/src/components/Pagination/tests/Pagination.test.tsx
index afbfbde82de..f821307f45c 100644
--- a/src/components/Pagination/tests/Pagination.test.tsx
+++ b/src/components/Pagination/tests/Pagination.test.tsx
@@ -103,6 +103,18 @@ describe('<Pagination />', () => {
       const pagination = mountWithAppProvider(<Pagination label={label} />);
       expect(pagination.text()).toContain(label);
     });
+
+    it('has subdued text without next and previous pages', () => {
+      const label = 'test';
+      const variation = 'subdued';
+      const pagination = mountWithAppProvider(<Pagination label={label} />);
+      expect(
+        pagination
+          .find('.Label')
+          .children()
+          .prop('variation'),
+      ).toStrictEqual(variation);
+    });
   });
 
   it('adds a keypress event for nextKeys', () => {

From 2432c5316903c0630933fbdc740159f5b8baecdc Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Wed, 18 Sep 2019 16:35:25 -0400
Subject: [PATCH 11/14] Response to feedback from PR review

---
 UNRELEASED.md                             |  2 ++
 src/components/Pagination/Pagination.scss |  4 ----
 src/components/Pagination/Pagination.tsx  | 18 ++++++++----------
 3 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/UNRELEASED.md b/UNRELEASED.md
index 650bc540297..da7e0023e00 100644
--- a/UNRELEASED.md
+++ b/UNRELEASED.md
@@ -10,6 +10,8 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
 
 ### Enhancements
 
+- Added new label prop to `Pagination` which is used to insert contextual info between navigation buttons [#2098](https://github.com/Shopify/polaris-react/pull/2098)
+
 ### Bug fixes
 
 ### Documentation
diff --git a/src/components/Pagination/Pagination.scss b/src/components/Pagination/Pagination.scss
index 28e7205a34a..707221e1e90 100644
--- a/src/components/Pagination/Pagination.scss
+++ b/src/components/Pagination/Pagination.scss
@@ -168,10 +168,6 @@ $stacking-order: (
   border-bottom-left-radius: 0;
 }
 
-.ButtonWithLabel {
-  border-radius: border-radius();
-}
-
 .Label {
   padding: 0 spacing(tight);
   display: flex;
diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index 1d2af304812..af4b9a254bf 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -68,16 +68,14 @@ export function Pagination({
     accessibilityLabel || intl.translate('Polaris.Pagination.pagination');
 
   const className = classNames(styles.Pagination, plain && styles.plain);
-  const previousClassName = classNames(
-    styles.Button,
-    styles.PreviousButton,
-    label && styles.ButtonWithLabel,
-  );
-  const nextClassName = classNames(
-    styles.Button,
-    styles.NextButton,
-    label && styles.ButtonWithLabel,
-  );
+
+  const previousClassName = !label
+    ? classNames(styles.Button, styles.PreviousButton)
+    : classNames(styles.Button);
+
+  const nextClassName = !label
+    ? classNames(styles.Button, styles.NextButton)
+    : classNames(styles.Button);
 
   const previousButton = previousURL ? (
     <UnstyledLink

From 0f6e201fe882f280dac619bf1206f87ba7d56488 Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Mon, 23 Sep 2019 09:22:29 -0400
Subject: [PATCH 12/14] Edited class assigment logic

---
 src/components/Pagination/Pagination.tsx | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/components/Pagination/Pagination.tsx b/src/components/Pagination/Pagination.tsx
index af4b9a254bf..fc25523b95b 100644
--- a/src/components/Pagination/Pagination.tsx
+++ b/src/components/Pagination/Pagination.tsx
@@ -69,13 +69,12 @@ export function Pagination({
 
   const className = classNames(styles.Pagination, plain && styles.plain);
 
-  const previousClassName = !label
-    ? classNames(styles.Button, styles.PreviousButton)
-    : classNames(styles.Button);
+  const previousClassName = classNames(
+    styles.Button,
+    !label && styles.PreviousButton,
+  );
 
-  const nextClassName = !label
-    ? classNames(styles.Button, styles.NextButton)
-    : classNames(styles.Button);
+  const nextClassName = classNames(styles.Button, !label && styles.NextButton);
 
   const previousButton = previousURL ? (
     <UnstyledLink

From 93a10e57b91bd377f1c3c49060670a31110ad8f0 Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Mon, 23 Sep 2019 09:33:58 -0400
Subject: [PATCH 13/14] Cleaned up some tests

---
 .../Pagination/tests/Pagination.test.tsx       | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/src/components/Pagination/tests/Pagination.test.tsx b/src/components/Pagination/tests/Pagination.test.tsx
index f821307f45c..437b0900108 100644
--- a/src/components/Pagination/tests/Pagination.test.tsx
+++ b/src/components/Pagination/tests/Pagination.test.tsx
@@ -80,13 +80,10 @@ describe('<Pagination />', () => {
 
   describe('accessibilityLabel', () => {
     it('inserts prop as aria-label', () => {
-      const accessibilityLabel = 'test';
       const pagination = mountWithAppProvider(
-        <Pagination accessibilityLabel={accessibilityLabel} />,
-      );
-      expect(pagination.find('nav').prop('aria-label')).toStrictEqual(
-        accessibilityLabel,
+        <Pagination accessibilityLabel="test" />,
       );
+      expect(pagination.find('nav').prop('aria-label')).toStrictEqual('test');
     });
 
     it('uses default value for aria-label', () => {
@@ -99,21 +96,18 @@ describe('<Pagination />', () => {
 
   describe('label', () => {
     it('renders as text', () => {
-      const label = 'test';
-      const pagination = mountWithAppProvider(<Pagination label={label} />);
-      expect(pagination.text()).toContain(label);
+      const pagination = mountWithAppProvider(<Pagination label="test" />);
+      expect(pagination.text()).toContain('test');
     });
 
     it('has subdued text without next and previous pages', () => {
-      const label = 'test';
-      const variation = 'subdued';
-      const pagination = mountWithAppProvider(<Pagination label={label} />);
+      const pagination = mountWithAppProvider(<Pagination label="test" />);
       expect(
         pagination
           .find('.Label')
           .children()
           .prop('variation'),
-      ).toStrictEqual(variation);
+      ).toStrictEqual('subdued');
     });
   });
 

From 795176a7b26695899fea9b39755b3db38d4214ac Mon Sep 17 00:00:00 2001
From: Mitchell Soares <mitchell.soares@shopify.com>
Date: Mon, 23 Sep 2019 09:41:52 -0400
Subject: [PATCH 14/14] Added new description of Pagination with the label prop
 in the component README

---
 src/components/Pagination/README.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/components/Pagination/README.md b/src/components/Pagination/README.md
index 5579d879e01..c04906d381a 100644
--- a/src/components/Pagination/README.md
+++ b/src/components/Pagination/README.md
@@ -9,6 +9,7 @@ keywords:
   - lists
   - detail
   - page
+  - label
   - pager
   - previous
   - next
@@ -96,6 +97,24 @@ Attach standard keyboard shortcuts to important pagination controls.
 </div>
 ```
 
+### Pagination with label
+
+Add a label between navigation buttons to provide more context of the content being viewed by the user.
+
+```jsx
+<Pagination
+  label="Results"
+  hasPrevious
+  onPrevious={() => {
+    console.log('Previous');
+  }}
+  hasNext
+  onNext={() => {
+    console.log('Next');
+  }}
+/>
+```
+
 ### Infinite scroll
 
 <!-- example-for: ios, android -->