feat(paginator): Add functionality to jump to first and last page

Add two buttons which allow you to jump to the first and last page.
Hidden by default and can be toggled with showHideFirstButtons

Fixes #9278

Author: lharries

src/demo-app/table/table-demo.html

@@ -172,6 +172,24 @@ <h3>MatTable Example</h3>
   </mat-paginator>
 </div>
 
+<h3>MatTable with First/Last Buttons Example</h3>
+
+<div class="demo-table-container demo-mat-table-example mat-elevation-z4">
+
+  <table-header-demo>
+  </table-header-demo>
+
+  <h4 class="paginator-output">{{paginatorOutput | json}}</h4>
+
+  <mat-paginator #paginator
+                [length]="_peopleDatabase.data.length"
+                [pageSize]="10"
+                [pageSizeOptions]="[5, 10, 25, 100]"
+                showFirstLastButtons
+                (page)="handlePaginator($event)">
+  </mat-paginator>
+</div>
+
 <mat-card class="demo-table-card">
   <h3> MatTable Using 'When' Rows for Interactive Details</h3>
 

src/demo-app/table/table-demo.scss

@@ -141,3 +141,7 @@
     background: #f5f5f5;
   }
 }
+
+.paginator-output {
+  margin-left: 20px;
+}

src/demo-app/table/table-demo.ts

@@ -9,7 +9,7 @@
 import {Component, ElementRef, ViewChild} from '@angular/core';
 import {PeopleDatabase, UserData} from './people-database';
 import {PersonDataSource} from './person-data-source';
-import {MatPaginator, MatSort, MatTableDataSource} from '@angular/material';
+import {MatPaginator, MatSort, MatTableDataSource, PageEvent} from '@angular/material';
 import {DetailRow, PersonDetailDataSource} from './person-detail-data-source';
 import {animate, state, style, transition, trigger} from '@angular/animations';
 import {SelectionModel} from '@angular/cdk/collections';
@@ -65,6 +65,8 @@ export class TableDemo {
   @ViewChild('paginatorForDataSource') paginatorForDataSource: MatPaginator;
   @ViewChild('sortForDataSource') sortForDataSource: MatSort;
 
+  paginatorOutput: PageEvent;
+
   constructor(public _peopleDatabase: PeopleDatabase) {
     this.matTableDataSource.sortingDataAccessor = (data: UserData, property: string) => {
       switch (property) {
@@ -183,4 +185,8 @@ export class TableDemo {
   toggleHighlight(property: string, enable: boolean) {
     enable ? this.highlights.add(property) : this.highlights.delete(property);
   }
+
+  handlePaginator(pageEvent: PageEvent) {
+    this.paginatorOutput = pageEvent;
+  }
 }

src/lib/paginator/_paginator-theme.scss

@@ -16,15 +16,22 @@
     color: mat-color($foreground, secondary-text);
   }
 
-  .mat-paginator-increment,
-  .mat-paginator-decrement {
+  .mat-paginator-decrement,
+  .mat-paginator-increment {
     border-top: 2px solid mat-color($foreground, 'icon');
     border-right: 2px solid mat-color($foreground, 'icon');
   }
 
+  .mat-paginator-first,
+  .mat-paginator-last {
+    border-top: 2px solid mat-color($foreground, 'icon');
+  }
+
   .mat-icon-button[disabled] {
+    .mat-paginator-decrement,
     .mat-paginator-increment,
-    .mat-paginator-decrement {
+    .mat-paginator-first,
+    .mat-paginator-last {
       border-color: mat-color($foreground, 'disabled');
     }
   }

src/lib/paginator/paginator-intl.ts

@@ -30,6 +30,12 @@ export class MatPaginatorIntl {
   /** A label for the button that decrements the current page. */
   previousPageLabel: string = 'Previous page';
 
+  /** A label for the button that moves to the first page. */
+  firstPageLabel: string = 'First page';
+
+  /** A label for the button that moves to the last page. */
+  lastPageLabel: string = 'Last page';
+
   /** A label for the range of items within the current page and the length of the whole list. */
   getRangeLabel = (page: number, pageSize: number, length: number) => {
     if (length == 0 || pageSize == 0) { return `0 of ${length}`; }

src/lib/paginator/paginator.html

@@ -25,14 +25,25 @@
       {{_intl.getRangeLabel(pageIndex, pageSize, length)}}
     </div>
 
+    <button mat-icon-button type="button"
+            class="mat-paginator-navigation-first"
+            (click)="firstPage()"
+            [attr.aria-label]="_intl.firstPageLabel"
+            [matTooltip]="_intl.firstPageLabel"
+            [matTooltipPosition]="'above'"
+            [disabled]="!hasPreviousPage()"
+            *ngIf="showFirstLastButtons">
+      <div class="mat-paginator-first"></div>
+      <div class="mat-paginator-decrement"></div>
+    </button>
     <button mat-icon-button type="button"
             class="mat-paginator-navigation-previous"
             (click)="previousPage()"
             [attr.aria-label]="_intl.previousPageLabel"
             [matTooltip]="_intl.previousPageLabel"
             [matTooltipPosition]="'above'"
             [disabled]="!hasPreviousPage()">
-      <div class="mat-paginator-increment"></div>
+      <div class="mat-paginator-decrement"></div>
     </button>
     <button mat-icon-button type="button"
             class="mat-paginator-navigation-next"
@@ -41,7 +52,18 @@
             [matTooltip]="_intl.nextPageLabel"
             [matTooltipPosition]="'above'"
             [disabled]="!hasNextPage()">
-      <div class="mat-paginator-decrement"></div>
+      <div class="mat-paginator-increment"></div>
+    </button>
+    <button mat-icon-button type="button"
+            class="mat-paginator-navigation-last"
+            (click)="lastPage()"
+            [attr.aria-label]="_intl.lastPageLabel"
+            [matTooltip]="_intl.lastPageLabel"
+            [matTooltipPosition]="'above'"
+            [disabled]="!hasNextPage()"
+            *ngIf="showFirstLastButtons">
+      <div class="mat-paginator-increment"></div>
+      <div class="mat-paginator-last"></div>
     </button>
   </div>
 </div>

src/lib/paginator/paginator.md

@@ -26,4 +26,4 @@ This will allow you to change the following:
  3. The tooltip messages on the navigation buttons.
 
 ### Accessibility
-The `aria-label`s for next page and previous page buttons can be set in `MatPaginatorIntl`.
+The `aria-label`s for next page, previous page, first page and last page buttons can be set in `MatPaginatorIntl`.

src/lib/paginator/paginator.scss

@@ -15,8 +15,18 @@ $mat-paginator-button-margin: 8px;
 $mat-paginator-button-icon-height: 8px;
 $mat-paginator-button-icon-width: 8px;
 
-$mat-paginator-button-decrement-icon-margin: 12px;
-$mat-paginator-button-increment-icon-margin: 16px;
+$mat-paginator-button-increment-icon-margin: 12px;
+$mat-paginator-button-decrement-icon-margin: 16px;
+
+$mat-paginator-button-first-last-icon-width: 14px;
+
+$mat-paginator-button-first-icon-margin: 3px;
+$mat-paginator-button-last-icon-margin: 15px;
+
+
+$mat-paginator-button-first-decrement-icon-margin: 21px;
+$mat-paginator-button-last-increment-icon-margin: 9px;
+
 
 .mat-paginator {
   display: block;
@@ -50,43 +60,71 @@ $mat-paginator-button-increment-icon-margin: 16px;
   margin: $mat-paginator-range-label-margin;
 }
 
-.mat-paginator-increment-button + .mat-paginator-increment-button {
+.mat-paginator-decrement-button + .mat-paginator-decrement-button {
   margin: 0 0 0 $mat-paginator-button-margin;
 
   [dir='rtl'] & {
     margin: 0 $mat-paginator-button-margin 0 0;
   }
 }
 
-.mat-paginator-increment,
-.mat-paginator-decrement {
+.mat-paginator-decrement,
+.mat-paginator-increment {
   width: $mat-paginator-button-icon-width;
   height: $mat-paginator-button-icon-height;
 }
 
-.mat-paginator-decrement,
-[dir='rtl'] .mat-paginator-increment {
-  transform: rotate(45deg);
-}
 .mat-paginator-increment,
 [dir='rtl'] .mat-paginator-decrement {
+  transform: rotate(45deg);
+}
+.mat-paginator-decrement,
+[dir='rtl'] .mat-paginator-increment {
   transform: rotate(225deg);
 }
 
+.mat-paginator-increment {
+  margin-left: $mat-paginator-button-increment-icon-margin;
+  [dir='rtl'] & {
+    margin-right: $mat-paginator-button-increment-icon-margin;
+  }
+}
+
 .mat-paginator-decrement {
   margin-left: $mat-paginator-button-decrement-icon-margin;
   [dir='rtl'] & {
     margin-right: $mat-paginator-button-decrement-icon-margin;
   }
 }
 
-.mat-paginator-increment {
-  margin-left: $mat-paginator-button-increment-icon-margin;
-  [dir='rtl'] & {
-    margin-right: $mat-paginator-button-increment-icon-margin;
+.mat-paginator-first {
+  transform: rotate(90deg);
+  width: $mat-paginator-button-first-last-icon-width;
+  height: $mat-paginator-button-icon-height;
+  float:left;
+  margin-left: $mat-paginator-button-first-icon-margin;
+}
+
+.mat-paginator-navigation-first {
+  .mat-paginator-decrement {
+    margin-left: $mat-paginator-button-first-decrement-icon-margin;
   }
 }
 
+.mat-paginator-navigation-last {
+  .mat-paginator-increment {
+    float: left;
+    margin-left: $mat-paginator-button-last-increment-icon-margin;
+  }
+}
+
+.mat-paginator-last {
+  transform: rotate(90deg);
+  width: $mat-paginator-button-first-last-icon-width;
+  height: $mat-paginator-button-icon-height;
+  margin-left: $mat-paginator-button-last-icon-margin;
+}
+
 .mat-paginator-range-actions {
   display: flex;
   align-items: center;

src/lib/paginator/paginator.spec.ts

@@ -104,7 +104,7 @@ describe('MatPaginator', () => {
       }));
   });
 
-  describe('when navigating with the navigation buttons', () => {
+  describe('when navigating with the next and previous buttons', () => {
     it('should be able to go to the next page', () => {
       expect(paginator.pageIndex).toBe(0);
 
@@ -125,6 +125,58 @@ describe('MatPaginator', () => {
       expect(component.latestPageEvent ? component.latestPageEvent.pageIndex : null).toBe(0);
     });
 
+  });
+
+  it('should be able to show the first/last buttons', () => {
+    expect(getFirstButton(fixture))
+      .toBeNull('Expected first button to not exist.');
+
+    expect(getLastButton(fixture))
+      .toBeNull('Expected last button to not exist.');
+
+    fixture.componentInstance.showFirstLastButtons = true;
+    fixture.detectChanges();
+
+    expect(getFirstButton(fixture))
+      .toBeTruthy('Expected first button to be rendered.');
+
+    expect(getLastButton(fixture))
+      .toBeTruthy('Expected last button to be rendered.');
+
+  });
+
+  describe('when showing the first and last button', () => {
+
+    beforeEach(() => {
+      component.showFirstLastButtons = true;
+      fixture.detectChanges();
+    });
+
+    it('should show right aria-labels for first/last buttons', () => {
+      expect(getFirstButton(fixture).getAttribute('aria-label')).toBe('First page');
+      expect(getLastButton(fixture).getAttribute('aria-label')).toBe('Last page');
+    });
+
+    it('should be able to go to the last page via the last page button', () => {
+      expect(paginator.pageIndex).toBe(0);
+
+      dispatchMouseEvent(getLastButton(fixture), 'click');
+
+      expect(paginator.pageIndex).toBe(9);
+      expect(component.latestPageEvent ? component.latestPageEvent.pageIndex : null).toBe(9);
+    });
+
+    it('should be able to go to the first page via the first page button', () => {
+      paginator.pageIndex = 3;
+      fixture.detectChanges();
+      expect(paginator.pageIndex).toBe(3);
+
+      dispatchMouseEvent(getFirstButton(fixture), 'click');
+
+      expect(paginator.pageIndex).toBe(0);
+      expect(component.latestPageEvent ? component.latestPageEvent.pageIndex : null).toBe(0);
+    });
+
     it('should disable navigating to the next page if at last page', () => {
       component.goToLastPage();
       fixture.detectChanges();
@@ -148,6 +200,7 @@ describe('MatPaginator', () => {
       expect(component.latestPageEvent).toBe(null);
       expect(paginator.pageIndex).toBe(0);
     });
+
   });
 
   it('should mark for check when inputs are changed directly', () => {
@@ -253,7 +306,7 @@ describe('MatPaginator', () => {
     expect(fixture.nativeElement.querySelector('.mat-select')).toBeNull();
   });
 
- it('should handle the number inputs being passed in as strings', () => {
+  it('should handle the number inputs being passed in as strings', () => {
     const withStringFixture = TestBed.createComponent(MatPaginatorWithStringValues);
     const withStringPaginator = withStringFixture.componentInstance.paginator;
 
@@ -277,6 +330,7 @@ describe('MatPaginator', () => {
     expect(element.querySelector('.mat-paginator-page-size'))
         .toBeNull('Expected select to be removed.');
   });
+
 });
 
 function getPreviousButton(fixture: ComponentFixture<any>) {
@@ -287,12 +341,21 @@ function getNextButton(fixture: ComponentFixture<any>) {
   return fixture.nativeElement.querySelector('.mat-paginator-navigation-next');
 }
 
+function getFirstButton(fixture: ComponentFixture<any>) {
+    return fixture.nativeElement.querySelector('.mat-paginator-navigation-first');
+}
+
+function getLastButton(fixture: ComponentFixture<any>) {
+    return fixture.nativeElement.querySelector('.mat-paginator-navigation-last');
+}
+
 @Component({
   template: `
     <mat-paginator [pageIndex]="pageIndex"
                    [pageSize]="pageSize"
                    [pageSizeOptions]="pageSizeOptions"
                    [hidePageSize]="hidePageSize"
+                   [showFirstLastButtons]="showFirstLastButtons"
                    [length]="length"
                    (page)="latestPageEvent = $event">
     </mat-paginator>
@@ -303,6 +366,7 @@ class MatPaginatorApp {
   pageSize = 10;
   pageSizeOptions = [5, 10, 25, 100];
   hidePageSize = false;
+  showFirstLastButtons = false;
   length = 100;
 
   latestPageEvent: PageEvent | null;