From 1d339e638d35f7f497dab4e27f167f659316b387 Mon Sep 17 00:00:00 2001
From: Jeremy Elbourn <jelbourn@google.com>
Date: Tue, 4 May 2021 15:57:44 -0400
Subject: [PATCH] fix(material/paginator): add `role="group"` to host (#22512)

In testing `<mat-paginator>` with VoiceOver, I found that the interaction was much nicer when the paginator controls were semantically grouped with `role="group"`. This change adds the role and updates the documentation to explicitly instruct users to apply a meaningful label.

(cherry picked from commit f06ff2a435682c16d146a1e8b68a4aee065f36be)
---
 src/material-experimental/mdc-paginator/paginator.spec.ts | 6 ++++++
 src/material-experimental/mdc-paginator/paginator.ts      | 1 +
 src/material/paginator/paginator.md                       | 7 ++++++-
 src/material/paginator/paginator.spec.ts                  | 6 ++++++
 src/material/paginator/paginator.ts                       | 1 +
 5 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/material-experimental/mdc-paginator/paginator.spec.ts b/src/material-experimental/mdc-paginator/paginator.spec.ts
index abc980a1412b..514430fea8a5 100644
--- a/src/material-experimental/mdc-paginator/paginator.spec.ts
+++ b/src/material-experimental/mdc-paginator/paginator.spec.ts
@@ -467,6 +467,12 @@ describe('MDC-based MatPaginator', () => {
     expect(paginator.showFirstLastButtons).toBe(true);
   });
 
+  it('should set `role="group"` on the host element', () => {
+    const fixture = createComponent(MatPaginatorApp);
+    const hostElement = fixture.nativeElement.querySelector('mat-paginator');
+    expect(hostElement.getAttribute('role')).toBe('group');
+  });
+
 });
 
 function getPreviousButton(fixture: ComponentFixture<any>) {
diff --git a/src/material-experimental/mdc-paginator/paginator.ts b/src/material-experimental/mdc-paginator/paginator.ts
index 355415c16ef8..d511f84aa58e 100644
--- a/src/material-experimental/mdc-paginator/paginator.ts
+++ b/src/material-experimental/mdc-paginator/paginator.ts
@@ -57,6 +57,7 @@ export const MAT_PAGINATOR_DEFAULT_OPTIONS =
   inputs: ['disabled'],
   host: {
     'class': 'mat-mdc-paginator',
+    'role': 'group',
   },
   changeDetection: ChangeDetectionStrategy.OnPush,
   encapsulation: ViewEncapsulation.None,
diff --git a/src/material/paginator/paginator.md b/src/material/paginator/paginator.md
index 4359b57dc7a1..e824c26d1679 100644
--- a/src/material/paginator/paginator.md
+++ b/src/material/paginator/paginator.md
@@ -26,4 +26,9 @@ This will allow you to change the following:
  3. The tooltip messages on the navigation buttons.
 
 ### Accessibility
-The `aria-label`s for next page, previous page, first page and last page buttons can be set in `MatPaginatorIntl`.
+The paginator uses `role="group"` to semantically group its child controls. You must add an
+`aria-label` or `aria-labelledby` attribute to `<mat-paginator>` with a label that describes
+the content controlled by the pagination control.
+
+You can set the `aria-label` attributes for the button and select controls within the paginator in 
+`MatPaginatorIntl`.
diff --git a/src/material/paginator/paginator.spec.ts b/src/material/paginator/paginator.spec.ts
index e2aedc2e01c4..01caf29d59d0 100644
--- a/src/material/paginator/paginator.spec.ts
+++ b/src/material/paginator/paginator.spec.ts
@@ -467,6 +467,12 @@ describe('MatPaginator', () => {
     expect(paginator.showFirstLastButtons).toBe(true);
   });
 
+  it('should set `role="group"` on the host element', () => {
+    const fixture = createComponent(MatPaginatorApp);
+    const hostElement = fixture.nativeElement.querySelector('mat-paginator');
+    expect(hostElement.getAttribute('role')).toBe('group');
+  });
+
 });
 
 function getPreviousButton(fixture: ComponentFixture<any>) {
diff --git a/src/material/paginator/paginator.ts b/src/material/paginator/paginator.ts
index 1dbab2c2a19f..8f59be8e2e1a 100644
--- a/src/material/paginator/paginator.ts
+++ b/src/material/paginator/paginator.ts
@@ -357,6 +357,7 @@ export abstract class _MatPaginatorBase<O extends {
   inputs: ['disabled'],
   host: {
     'class': 'mat-paginator',
+    'role': 'group',
   },
   changeDetection: ChangeDetectionStrategy.OnPush,
   encapsulation: ViewEncapsulation.None,