docs(sort): add initial sorting docs (#5513)

* docs(sort): add initial sorting docs

* add newlines

* update

* minor

* rebase, add table example

src/lib/sort/sort.md

@@ -0,0 +1,35 @@
+The `mdSort` and `md-sort-header` are used, respectively, to add sorting state and display
+to tabular data.
+
+<!-- example(sort-overview) -->
+
+### Adding sort to table headers
+
+To add sorting behavior and styling to a set of table headers, add the `<md-sort-header>` component
+to each header and provide an `id` that will identify it. These headers should be contained within a
+parent element with the `mdSort` directive, which will emit an `mdSortChange` event when the user
+ triggers sorting on the header.
+
+Users can trigger the sort header through a mouse click or keyboard action. When this happens, the
+`mdSort` will emit an `mdSortChange` event that contains the ID of the header triggered and the
+direction to sort (`asc` or `desc`).
+
+#### Changing the sort order
+
+By default, a sort header starts its sorting at `asc` and then `desc`. Triggering the sort header
+after `desc` will remove sorting.
+
+To reverse the sort order for all headers, set the `mdSortStart` to `desc` on the `mdSort` 
+directive. To reverse the order only for a specific header, set the `start` input only on the header 
+instead.
+
+To prevent the user from clearing the sort sort state from an already sorted column, set 
+`mdSortDisableClear` to `true` on the `mdSort` to affect all headers, or set `disableClear` to 
+`true` on a specific header.
+
+#### Using sort with the md-table
+
+When used on an `md-table` header, it is not required to set an `md-sort-header` id on because
+by default it will use the id of the column.
+
+<!-- example(table-sorting) -->

src/material-examples/example-module.ts

@@ -98,6 +98,7 @@ import {TableBasicExample} from './table-basic/table-basic-example';
 import {TableSortingExample} from './table-sorting/table-sorting-example';
 import {TableFilteringExample} from './table-filtering/table-filtering-example';
 import {CdkTableBasicExample} from './cdk-table-basic/cdk-table-basic-example';
+import {SortOverviewExample} from './sort-overview/sort-overview-example';
 
 export interface LiveExample {
   title: string;
@@ -197,6 +198,7 @@ export const EXAMPLE_COMPONENTS = {
   },
   'slide-toggle-forms': {title: 'Slide-toggle with forms', component: SlideToggleFormsExample},
   'slide-toggle-overview': {title: 'Basic slide-toggles', component: SlideToggleOverviewExample},
+  'sort-overview': {title: 'Sorting overview', component: SortOverviewExample},
   'snack-bar-component': {
     title: 'Snack-bar with a custom component',
     component: SnackBarComponentExample
@@ -312,6 +314,7 @@ export const EXAMPLE_LIST = [
   SlideToggleConfigurableExample,
   SlideToggleOverviewExample,
   SlideToggleFormsExample,
+  SortOverviewExample,
   SnackBarComponentExample,
   PizzaPartyComponent,
   SnackBarOverviewExample,

src/material-examples/sort-overview/sort-overview-example.css

@@ -0,0 +1,3 @@
+.mat-sort-header-container {
+  align-items: center;
+}

src/material-examples/sort-overview/sort-overview-example.html

@@ -0,0 +1,17 @@
+<table mdSort (mdSortChange)="sortData($event)">
+  <tr>
+    <th md-sort-header="name">Dessert (100g)</th>
+    <th md-sort-header="calories">Calories</th>
+    <th md-sort-header="fat">Fat (g)</th>
+    <th md-sort-header="carbs">Carbs (g)</th>
+    <th md-sort-header="protein">Protein (g)</th>
+  </tr>
+
+  <tr *ngFor="let dessert of sortedData">
+    <td>{{dessert.name}}</td>
+    <td>{{dessert.calories}}</td>
+    <td>{{dessert.fat}}</td>
+    <td>{{dessert.carbs}}</td>
+    <td>{{dessert.protein}}</td>
+  </tr>
+</table>

src/material-examples/sort-overview/sort-overview-example.ts

@@ -0,0 +1,48 @@
+import {Component} from '@angular/core';
+import {Sort} from '@angular/material';
+
+
+@Component({
+  selector: 'sort-overview-example',
+  templateUrl: 'sort-overview-example.html',
+  styleUrls: ['sort-overview-example.css'],
+})
+export class SortOverviewExample {
+  desserts = [
+    {name: 'Frozen yogurt', calories: '159', fat: '6', carbs: '24', protein: '4'},
+    {name: 'Ice cream sandwich', calories: '237', fat: '9', carbs: '37', protein: '4'},
+    {name: 'Eclair', calories: '262', fat: '16', carbs: '24', protein: '6'},
+    {name: 'Cupcake', calories: '305', fat: '4', carbs: '67', protein: '4'},
+    {name: 'Gingerbread', calories: '356', fat: '16', carbs: '49', protein: '4'},
+  ];
+
+  sortedData;
+
+  constructor() {
+    this.sortedData = this.desserts.slice();
+  }
+
+  sortData(sort: Sort) {
+    const data = this.desserts.slice();
+    if (!sort.active || sort.direction == '') {
+      this.sortedData = data;
+      return;
+    }
+
+    this.sortedData = data.sort((a, b) => {
+      let isAsc = sort.direction == 'asc';
+      switch (sort.active) {
+        case 'name': return compare(a.name, b.name, isAsc);
+        case 'calories': return compare(+a.calories, +b.calories, isAsc);
+        case 'fat': return compare(+a.fat, +b.fat, isAsc);
+        case 'carbs': return compare(+a.carbs, +b.carbs, isAsc);
+        case 'protein': return compare(+a.protein, +b.protein, isAsc);
+        default: return 0;
+      }
+    });
+  }
+}
+
+function compare(a, b, isAsc) {
+  return (a < b ? -1 : 1) * (isAsc ? 1 : -1);
+}