add examples and readme

Author: andrewseguin

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

@@ -43,9 +43,9 @@
   </cdk-table>
 
   <md-paginator #paginator
+                [listLength]="_peopleDatabase.data.length"
                 [currentPageIndex]="0"
                 [pageLength]="10"
-                [listLength]="_peopleDatabase.data.length"
                 [pageLengthOptions]="[5, 10, 25, 100]">
   </md-paginator>
 </div>

src/lib/core/testing/jasmine-matchers.ts

@@ -10,21 +10,35 @@
  * Collection of useful custom jasmine matchers for tests.
  */
 export const customMatchers: jasmine.CustomMatcherFactories = {
+  /** Matcher verifying that the element has the expected role attribute. */
   toBeRole: () => {
     return {
       compare: function (element: Element, expectedRole: string) {
-        const result: jasmine.CustomMatcherResult = {pass: false};
-        const actualRole = element.getAttribute('role');
-
-        result.pass = actualRole === expectedRole;
-        result.message = `Expected role for ${element.tagName} to be ${expectedRole}`;
-
-        if (!result.pass) {
-          result.message += ` but was ${actualRole}`;
-        }
+        return checkElementAttribute(element, 'role', expectedRole);
+      }
+    };
+  },
 
-        return result;
+  /** Matcher verifying that the element has the expected aria label. */
+  toHaveAriaLabel: () => {
+    return {
+      compare: function (element: Element, expectedAriaLabel: string) {
+        return checkElementAttribute(element, 'aria-label', expectedAriaLabel);
       }
     };
-  }
+  },
 };
+
+function checkElementAttribute(element, attr, expectation): jasmine.CustomMatcherResult {
+  const result: jasmine.CustomMatcherResult = {pass: false};
+  const actual = element.getAttribute(attr);
+
+  result.pass = actual === expectation;
+  result.message = `Expected aria-label for ${element.tagName} to be ${expectation}`;
+
+  if (!result.pass) {
+    result.message += ` but was ${actual}`;
+  }
+
+  return result;
+}

src/lib/core/theming/_all-theme.scss

@@ -14,6 +14,7 @@
 @import '../../input/input-theme';
 @import '../../list/list-theme';
 @import '../../menu/menu-theme';
+@import '../../paginator/paginator-theme';
 @import '../../progress-bar/progress-bar-theme';
 @import '../../progress-spinner/progress-spinner-theme';
 @import '../../radio/radio-theme';
@@ -44,6 +45,7 @@
   @include mat-input-theme($theme);
   @include mat-list-theme($theme);
   @include mat-menu-theme($theme);
+  @include mat-paginator-theme($theme);
   @include mat-progress-bar-theme($theme);
   @include mat-progress-spinner-theme($theme);
   @include mat-radio-theme($theme);

src/lib/core/typography/_all-typography.scss

@@ -12,6 +12,7 @@
 @import '../../input/input-theme';
 @import '../../list/list-theme';
 @import '../../menu/menu-theme';
+@import '../../paginator/paginator-theme';
 @import '../../progress-bar/progress-bar-theme';
 @import '../../progress-spinner/progress-spinner-theme';
 @import '../../radio/radio-theme';
@@ -41,6 +42,7 @@
   @include mat-icon-typography($config);
   @include mat-input-typography($config);
   @include mat-menu-typography($config);
+  @include mat-paginator-typography($config);
   @include mat-progress-bar-typography($config);
   @include mat-progress-spinner-typography($config);
   @include mat-radio-typography($config);

src/lib/paginator/_paginator-theme.scss

@@ -0,0 +1,39 @@
+@import '../core/theming/palette';
+@import '../core/theming/theming';
+@import '../core/typography/typography-utils';
+
+
+@mixin mat-paginator-theme($theme) {
+  $foreground: map-get($theme, foreground);
+
+  .mat-paginator,
+  .mat-paginator-page-length-select .mat-select-trigger {
+    color: mat-color($foreground, secondary-text);
+  }
+
+  .mat-paginator-increment,
+  .mat-paginator-decrement {
+    border-top: 2px solid mat-color($foreground, 'icon');
+    border-right: 2px solid mat-color($foreground, 'icon');
+
+    .mat-icon-button[disabled] & {
+      border-color: mat-color($foreground, 'disabled');
+    }
+  }
+}
+
+@mixin mat-paginator-typography($config) {
+  .mat-paginator {
+    font: {
+      family: mat-font-family($config);
+      size: mat-font-size($config, caption);
+    }
+  }
+
+  .mat-paginator-page-length-select .mat-select-trigger {
+    font: {
+      family: mat-font-family($config);
+      size: mat-font-size($config, caption);
+    }
+  }
+}

src/lib/paginator/index.ts

@@ -1,29 +1,33 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
 import {NgModule} from '@angular/core';
 import {CommonModule} from '@angular/common';
 import {FormsModule} from '@angular/forms';
 import {MdCommonModule, OverlayModule} from '../core';
-import {MdButtonModule} from '../button';
-import {MdSelectModule} from '../select';
+import {MdButtonModule} from '../button/index';
+import {MdSelectModule} from '../select/index';
 import {MdPaginator} from './paginator';
 import {MdPaginatorIntl} from './paginator-intl';
-import {MdTooltipModule} from '../tooltip';
+import {MdTooltipModule} from '../tooltip/index';
 
 
 @NgModule({
   imports: [
     CommonModule,
     FormsModule,
     MdButtonModule,
-    MdCommonModule,
     MdSelectModule,
     MdTooltipModule,
-    OverlayModule,
   ],
   exports: [MdPaginator],
   declarations: [MdPaginator],
-  providers: [
-    MdPaginatorIntl,
-  ],
+  providers: [MdPaginatorIntl],
 })
 export class MdPaginatorModule {}
 

src/lib/paginator/paginator-intl.ts

@@ -1,22 +1,40 @@
-import {Injectable} from '@angular/core';
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
 
+import {Injectable} from '@angular/core';
 
-/** Paginator labels that require internationalization. */
+/**
+ * Paginator labels that require internationalization. To modify the labels and text displayed,
+ * extend this class with custom values and inject it as a custom provider.
+ */
 @Injectable()
 export class MdPaginatorIntl {
   /** A label for the page size selector. */
   itemsPerPageLabel = 'Items per page:';
 
   /** A label for the button that increments the current page. */
-  incrementLabel = 'Next page';
+  nextPageLabel = 'Next page';
 
   /** A label for the button that decrements the current page. */
-  decrementLabel = 'Previous page';
+  previousPageLabel = 'Previous page';
 
   getRangeLabel(currentPage: number, pageSize: number, listLength: number) {
+    if (listLength == 0 || pageSize == 0) { return `0 of ${listLength}`}
+
+    listLength = Math.max(listLength, 0);
+
     const startIndex = currentPage * pageSize;
-    const endIndex = Math.min(startIndex + pageSize, listLength);
 
-    return `${currentPage * pageSize + 1} - ${endIndex} of ${listLength}`;
+    // If the start index exceeds the list length, do not try and fix the end index to the end.
+    const endIndex = startIndex < listLength ?
+        Math.min(startIndex + pageSize, listLength) :
+        startIndex + pageSize;
+
+    return `${startIndex + 1} - ${endIndex} of ${listLength}`;
   }
 }

src/lib/paginator/paginator.html

@@ -1,33 +1,39 @@
 <div class="mat-paginator-page-length-select">
-  {{_intl.itemsPerPageLabel}}
-  <md-select [ngModel]="pageLength"
-             [attr.aria-label]="_intl.itemsPerPageLabel"
+  <div class="mat-paginator-items-per-page-label">
+    {{_intl.itemsPerPageLabel}}
+  </div>
+
+  <md-select *ngIf="_displayedPageLengthOptions.length > 1"
+             [ngModel]="pageLength"
+             [aria-label]="_intl.itemsPerPageLabel"
              (change)="_changePageLength($event.value)">
-    <md-option *ngFor="let pageLengthOption of pageLengthOptions" [value]="pageLengthOption">
+    <md-option *ngFor="let pageLengthOption of _displayedPageLengthOptions" [value]="pageLengthOption">
       {{pageLengthOption}}
     </md-option>
   </md-select>
+
+  <div *ngIf="_displayedPageLengthOptions.length <= 1">{{pageLength}}</div>
 </div>
 
 <div class="mat-paginator-range-label">
   {{_intl.getRangeLabel(currentPageIndex, pageLength, listLength)}}
 </div>
 
 <button md-icon-button
-        class="mat-paginator-increment-button"
-        (click)="incrementPage(-1)"
-        [attr.aria-label]="_intl.decrementLabel"
-        [mdTooltip]="_intl.decrementLabel"
+        class="mat-paginator-navigation-button mat-paginator-navigation-previous"
+        (click)="navigateToPreviousPage()"
+        [attr.aria-label]="_intl.previousPageLabel"
+        [mdTooltip]="_intl.previousPageLabel"
         [mdTooltipPosition]="'above'"
-        [disabled]="!_canIncrementPage(-1)">
+        [disabled]="!canNavigateToPreviousPage(-1)">
   <div class="mat-paginator-increment"></div>
 </button>
 <button md-icon-button
-        class="mat-paginator-increment-button"
-        (click)="incrementPage(1)"
-        [attr.aria-label]="_intl.incrementLabel"
-        [mdTooltip]="_intl.incrementLabel"
+        class="mat-paginator-navigation-button mat-paginator-navigation-next"
+        (click)="navigateToNextPage()"
+        [attr.aria-label]="_intl.nextPageLabel"
+        [mdTooltip]="_intl.nextPageLabel"
         [mdTooltipPosition]="'above'"
-        [disabled]="!_canIncrementPage(1)">
+        [disabled]="!canNavigateToNextPage(1)">
   <div class="mat-paginator-decrement"></div>
 </button>

src/lib/paginator/paginator.md

@@ -0,0 +1,24 @@
+`<md-paginator>` is a component that provides navigation between paged information. It supports
+ the changing of page length as well as giving the user buttons to navigate to the previous or next
+ page.
+
+<!-- example(pagination-overview) -->
+
+To use the paginator, you must provide the total length of the pagination information list and
+the length of each page. To allow the end-user to change the page length list, you may optionally
+input an array of numbers that the user may select from.
+
+Additionally you may provide an input of what the current page index should be. Note that
+a non-zero index will be interpretted to display the first page, whereas if the page index is beyond
+the max number of pages, then this will be reflected to the user (e.g. `140 - 149 of 100 items`).
+
+When the user changes the page length, or navigates between pages, the paginator will output a
+`PageChangeEvent` that contains the paginator's context, including the list length,
+
+### Internationalization
+In order to support internationalization or customization of the displayed text, the paginator
+supports an injection of a custom class that extends `MdPaginatorIntl`. This will allow you to
+change the following:
+ 1. The label for the length of each page.
+ 2. The range text displayed to the user.
+ 3. The tooltip messages on the navigation buttons.

src/lib/paginator/paginator.scss

@@ -2,22 +2,23 @@
   display: flex;
   align-items: center;
   justify-content: flex-end;
-  font-size: 12px;
   min-height: 56px;
   padding: 0 8px;
-  color: rgba(0, 0, 0, 0.54);
+}
+
+.mat-paginator-items-per-page-label {
+  margin: 0 4px;
 }
 
 .mat-paginator-page-length-select {
   display: flex;
   align-items: center;
 
   .mat-select {
-    margin: 0 8px;
+    margin: 0 4px;
   }
 
   .mat-select-trigger {
-    font-size: 12px;
     min-width: 56px;
   }
 }
@@ -38,12 +39,6 @@
 .mat-paginator-decrement {
   width: 8px;
   height: 8px;
-  border-top: 2px solid #666;
-  border-right: 2px solid #666;
-
-  .mat-icon-button[disabled] & {
-    border-color: rgba(0, 0, 0, 0.25);
-  }
 }
 
 .mat-paginator-decrement,