feat(sort): fix animation; show on hover

Author: andrewseguin

src/lib/sort/sort-header.html

@@ -1,15 +1,23 @@
 <div class="mat-sort-header-container"
-     [class.mat-sort-header-position-before]="arrowPosition == 'before'">
+     [class.mat-sort-header-sorted]="_isSorted()"
+     [class.mat-sort-header-position-before]="viewState == 'before'">
   <button class="mat-sort-header-button" type="button"
+          (focus)="showIndicatorHint = true"
+          (blur)="showIndicatorHint = false"
           [attr.aria-label]="_intl.sortButtonLabel(id)">
     <ng-content></ng-content>
   </button>
 
-  <div *ngIf="_isSorted()" class="mat-sort-header-arrow" [@indicatorToggle]="_sort.direction">
+  <!-- Disable animations while a current animation is running -->
+  <div class="mat-sort-header-arrow"
+       [@arrowOpacity]="_getArrowViewState()"
+       [@arrowPosition]="_getArrowViewState()"
+       (@arrowPosition.start)="_disableStateAnimation = true"
+       (@arrowPosition.done)="_disableStateAnimation = false">
     <div class="mat-sort-header-stem"></div>
-    <div class="mat-sort-header-indicator" [@indicator]="_sort.direction" >
-      <div class="mat-sort-header-pointer-left" [@leftPointer]="_sort.direction"></div>
-      <div class="mat-sort-header-pointer-right" [@rightPointer]="_sort.direction"></div>
+    <div class="mat-sort-header-indicator" [@indicator]="_getArrowDirectionState()" >
+      <div class="mat-sort-header-pointer-left" [@leftPointer]="_getArrowDirectionState()"></div>
+      <div class="mat-sort-header-pointer-right" [@rightPointer]="_getArrowDirectionState()"></div>
       <div class="mat-sort-header-pointer-middle"></div>
     </div>
   </div>

src/lib/sort/sort-header.scss

@@ -3,7 +3,7 @@ $mat-sort-header-arrow-container-size: 12px;
 $mat-sort-header-arrow-stem-size: 10px;
 $mat-sort-header-arrow-pointer-length: 6px;
 $mat-sort-header-arrow-thickness: 2px;
-$mat-sort-header-arrow-transition: 225ms cubic-bezier(0.4, 0, 0.2, 1);
+$mat-sort-header-arrow-hint-opacity: 0.38;
 
 .mat-sort-header-container {
   display: flex;
@@ -56,7 +56,6 @@ $mat-sort-header-arrow-transition: 225ms cubic-bezier(0.4, 0, 0.2, 1);
   position: absolute;
   top: 0;
   left: 0;
-  transition: $mat-sort-header-arrow-transition;
 }
 
 .mat-sort-header-pointer-middle {
@@ -72,7 +71,6 @@ $mat-sort-header-arrow-transition: 225ms cubic-bezier(0.4, 0, 0.2, 1);
   background: currentColor;
   width: $mat-sort-header-arrow-pointer-length;
   height: $mat-sort-header-arrow-thickness;
-  transition: $mat-sort-header-arrow-transition;
   position: absolute;
   top: 0;
 }

src/lib/sort/sort-header.ts

@@ -15,25 +15,35 @@ import {
   ViewEncapsulation
 } from '@angular/core';
 import {coerceBooleanProperty} from '@angular/cdk/coercion';
-import {
-  trigger,
-  state,
-  style,
-  animate,
-  transition,
-  keyframes,
-} from '@angular/animations';
+import {animate, keyframes, state, style, transition, trigger} from '@angular/animations';
 import {CdkColumnDef} from '@angular/cdk/table';
 import {Subscription} from 'rxjs/Subscription';
 import {merge} from 'rxjs/observable/merge';
 import {MatSort, MatSortable} from './sort';
+import {SortDirection} from './sort-direction';
 import {MatSortHeaderIntl} from './sort-header-intl';
 import {getSortHeaderNotContainedWithinSortError} from './sort-errors';
 import {AnimationCurves, AnimationDurations} from '@angular/material/core';
 
 const SORT_ANIMATION_TRANSITION =
     AnimationDurations.ENTERING + ' ' + AnimationCurves.STANDARD_CURVE;
 
+/**
+ * Valid positions for the arrow to be in for its opacity and translation.
+ * @docs-private
+ */
+export type ArrowViewState = SortDirection | 'peek' | 'active';
+
+/**
+ * States describing the arrow's animated position (animating fromState -> toState).
+ * If the fromState is not defined, there will be no animated transition to the toState.
+ * @docs-private
+ */
+export interface ArrowViewStateTransition {
+  fromState?: ArrowViewState;
+  toState: ArrowViewState;
+}
+
 /**
  * Applies sorting behavior (click to change sort) and styles to an element, including an
  * arrow to display the current sort direction.
@@ -50,52 +60,135 @@ const SORT_ANIMATION_TRANSITION =
   templateUrl: 'sort-header.html',
   styleUrls: ['sort-header.css'],
   host: {
-    '(click)': '_sort.sort(this)',
-    '[class.mat-sort-header-sorted]': '_isSorted()',
+    '(click)': '_handleClick()',
+    '(mouseenter)': 'showIndicatorHint = true',
+    '(longpress)': 'showIndicatorHint = true',
+    '(mouseleave)': 'showIndicatorHint = false',
   },
   encapsulation: ViewEncapsulation.None,
   preserveWhitespaces: false,
   changeDetection: ChangeDetectionStrategy.OnPush,
   animations: [
+    // Individual arrow parts that show direction
     trigger('indicator', [
-      state('asc', style({transform: 'translateY(0px)'})),
+      state('active-asc, asc', style({transform: 'translateY(0px)'})),
       // 10px is the height of the sort indicator, minus the width of the pointers
-      state('desc', style({transform: 'translateY(10px)'})),
-      transition('asc <=> desc', animate(SORT_ANIMATION_TRANSITION))
+      state('active-desc, desc', style({transform: 'translateY(10px)'})),
+      transition('active-asc <=> active-desc', animate(SORT_ANIMATION_TRANSITION))
     ]),
     trigger('leftPointer', [
-      state('asc', style({transform: 'rotate(-45deg)'})),
-      state('desc', style({transform: 'rotate(45deg)'})),
-      transition('asc <=> desc', animate(SORT_ANIMATION_TRANSITION))
+      state('active-asc, asc', style({transform: 'rotate(-45deg)'})),
+      state('active-desc, desc', style({transform: 'rotate(45deg)'})),
+      transition('active-asc <=> active-desc', animate(SORT_ANIMATION_TRANSITION))
     ]),
     trigger('rightPointer', [
-      state('asc', style({transform: 'rotate(45deg)'})),
-      state('desc', style({transform: 'rotate(-45deg)'})),
-      transition('asc <=> desc', animate(SORT_ANIMATION_TRANSITION))
+      state('active-asc, asc', style({transform: 'rotate(45deg)'})),
+      state('active-desc, desc', style({transform: 'rotate(-45deg)'})),
+      transition('active-asc <=> active-desc', animate(SORT_ANIMATION_TRANSITION))
+    ]),
+
+    // Arrow opacity
+    trigger('arrowOpacity', [
+      state('desc-to-active, asc-to-active, active',
+          style({opacity: 1})),
+      state('desc-to-peek, asc-to-peek, peek',
+          style({opacity: .54})),
+      state('peek-to-desc, active-to-desc, desc, peek-to-asc, active-to-asc, asc',
+          style({opacity: 0})),
+      // Transition between all states except for immediate transitions
+      transition('* => asc, * => desc, * => active, * => peek', animate('0ms')),
+      transition('* <=> *', animate(SORT_ANIMATION_TRANSITION))
     ]),
-    trigger('indicatorToggle', [
-      transition('void => asc', animate(SORT_ANIMATION_TRANSITION, keyframes([
-        style({transform: 'translateY(25%)', opacity: 0}),
-        style({transform: 'none', opacity: 1})
+
+    // Translation of the arrow as a whole. States are separated into two groups: ones with
+    // animations and others that are immediate. Immediate states are asc, desc, peek, and active.
+    // The other states define a specific animation (source-to-destination) and are determined as
+    // a function of their prev user-perceived state and what the next state should be.
+    trigger('arrowPosition', [
+      // Hidden Above => Peek Center
+      transition('* => desc-to-peek, * => desc-to-active',
+          animate(SORT_ANIMATION_TRANSITION, keyframes([
+            style({transform: 'translateY(-25%)'}),
+            style({transform: 'translateY(0)'})
       ]))),
-      transition('asc => void', animate(SORT_ANIMATION_TRANSITION, keyframes([
-        style({transform: 'none', opacity: 1}),
-        style({transform: 'translateY(-25%)', opacity: 0})
+      // Peek Center => Hidden Below
+      transition('* => peek-to-desc, * => active-to-desc',
+          animate(SORT_ANIMATION_TRANSITION, keyframes([
+            style({transform: 'translateY(0)'}),
+            style({transform: 'translateY(25%)'})
       ]))),
-      transition('void => desc', animate(SORT_ANIMATION_TRANSITION, keyframes([
-        style({transform: 'translateY(-25%)', opacity: 0}),
-        style({transform: 'none', opacity: 1})
+      // Hidden Below => Peek Center
+      transition('* => asc-to-peek, * => asc-to-active',
+          animate(SORT_ANIMATION_TRANSITION, keyframes([
+            style({transform: 'translateY(25%)'}),
+            style({transform: 'translateY(0)'})
       ]))),
-      transition('desc => void', animate(SORT_ANIMATION_TRANSITION, keyframes([
-        style({transform: 'none', opacity: 1}),
-        style({transform: 'translateY(25%)', opacity: 0})
+      // Peek Center => Hidden Above
+      transition('* => peek-to-asc, * => active-to-asc',
+          animate(SORT_ANIMATION_TRANSITION, keyframes([
+            style({transform: 'translateY(0)'}),
+            style({transform: 'translateY(-25%)'})
       ]))),
+      state('desc-to-peek, asc-to-peek, peek, desc-to-active, asc-to-active, active',
+          style({transform: 'translateY(0)'})),
+      state('peek-to-desc, active-to-desc, desc',
+          style({transform: 'translateY(-25%)'})),
+      state('peek-to-asc, active-to-asc, asc',
+          style({transform: 'translateY(25%)'})),
     ])
   ]
 })
 export class MatSortHeader implements MatSortable {
   private _rerenderSubscription: Subscription;
 
+  /**
+   * Flag set to true when the indicator should be displayed while the sort is not active. Used to
+   * provide an affordance that the header is sortable by showing on focus and hover.
+   * @docs-private
+   */
+  set showIndicatorHint(showIndicatorHint: boolean) {
+    this._showIndicatorHint = showIndicatorHint;
+
+    if (!this._isSorted()) {
+      this._updateArrowDirection();
+      if (this.showIndicatorHint) {
+        this.viewState = {fromState: this._arrowDirection, toState: 'peek'};
+      } else {
+        this.viewState = {fromState: 'peek', toState: this._arrowDirection};
+      }
+    }
+  }
+  get showIndicatorHint(): boolean { return this._showIndicatorHint; }
+  _showIndicatorHint: boolean = false;
+
+  /**
+   * The view transition state of the arrow (translation/ opacity) - indicates its `from` and `to`
+   * position through the animation. If animations are currently disabled, the fromState is removed
+   * so that there is no animation displayed.
+   * @docs-private
+   */
+  set viewState(arrowPosition: ArrowViewStateTransition) {
+    this._viewState = arrowPosition;
+
+    // If the animation for arrow position state (opacity/translation) should be disabled,
+    // remove the fromState so that it jumps right to the toState.
+    if (this._disableViewStateAnimation) {
+      this._viewState = {toState: arrowPosition.toState};
+    }
+  }
+  get viewState(): ArrowViewStateTransition {
+    return this._viewState;
+  }
+  _viewState: ArrowViewStateTransition;
+
+  /** The direction the arrow should be facing according to the current state. */
+  _arrowDirection: SortDirection = '';
+
+  /**
+   * Whether the view state animation should show the transition between the `from` and `to` states.
+   */
+  _disableViewStateAnimation = false;
+
   /**
    * ID of this sort header. If used within the context of a CdkColumnDef, this will default to
    * the column's name.
@@ -123,6 +216,16 @@ export class MatSortHeader implements MatSortable {
     }
 
     this._rerenderSubscription = merge(_sort.sortChange, _intl.changes).subscribe(() => {
+      if (this._isSorted()) {
+        this._updateArrowDirection();
+      }
+
+      // If this header was recently active and now no longer sorted, animate away the arrow.
+      if (!this._isSorted() && this.viewState.toState === 'active') {
+        this._disableViewStateAnimation = false;
+        this.viewState = {fromState: 'active', toState: this._arrowDirection};
+      }
+
       changeDetectorRef.markForCheck();
     });
   }
@@ -132,6 +235,10 @@ export class MatSortHeader implements MatSortable {
       this.id = this._cdkColumnDef.name;
     }
 
+    // Initialize the direction of the arrow and set the view state to be immediately that state.
+    this._updateArrowDirection();
+    this.viewState = {toState: this._arrowDirection};
+
     this._sort.register(this);
   }
 
@@ -140,9 +247,49 @@ export class MatSortHeader implements MatSortable {
     this._rerenderSubscription.unsubscribe();
   }
 
+  /** Triggers the sort on this sort header and removes the indicator hint. */
+  _handleClick() {
+    this._sort.sort(this);
+
+    // Do not show the animation if the header was already shown in the right position.
+    if (this.viewState.toState === 'peek' || this.viewState.toState === 'active') {
+      this._disableViewStateAnimation = true;
+    }
+
+    // If the arrow is now sorted, animate the arrow into place. Otherwise, animate it away into
+    // the direction it is facing.
+    this.viewState = this._isSorted() ?
+        {fromState: this._arrowDirection, toState: 'active'} :
+        {fromState: 'active', toState: this._arrowDirection};
+
+    this._showIndicatorHint = false;
+  }
+
   /** Whether this MatSortHeader is currently sorted in either ascending or descending order. */
   _isSorted() {
     return this._sort.active == this.id &&
         (this._sort.direction === 'asc' || this._sort.direction === 'desc');
   }
+
+  /** Returns the animation state for the arrow direction (indicator and pointers). */
+  _getArrowDirectionState() {
+    return `${this._isSorted() ? 'active-' : ''}${this._arrowDirection}`;
+  }
+
+  /** Returns the arrow position state (opacity, translation). */
+  _getArrowViewState() {
+    const fromState = this.viewState.fromState;
+    return (fromState ? `${fromState}-to-` : '') + this.viewState.toState;
+  }
+
+  /**
+   * Updates the direction the arrow should be pointing. If it is not sorted, the arrow should be
+   * facing the start direction. Otherwise if it is sorted, the arrow should point in the currently
+   * active sorted direction.
+   */
+  _updateArrowDirection() {
+    this._arrowDirection = this._isSorted() ?
+        this._sort.direction :
+        (this.start || this._sort.start);
+  }
 }