update(ripple): remove deprecated speed factor option.

* Removes the deprecated `[matRippleSpeedFactor]` and global `baseSpeedFactor` option.
* Adds update rules that can automatically switch to the new API (as much as possible) and even calculate the new durations based on the previously specified speed factor.

BREAKING CHANGE: deprecated `[matRippleSpeedFactor]` and `baseSpeedFactor` for the ripples have been removed. Use the new animation config instead.

Author: devversion

src/lib/chips/chip.ts

@@ -229,10 +229,9 @@ export class MatChip extends _MatChipMixinBase implements FocusableOption, OnDes
     this._chipRipple.setupTriggerEvents(_elementRef.nativeElement);
 
     if (globalOptions) {
+      // TODO(paul): Do not copy each option manually. Allow dynamic global option changes: #9729
       this._ripplesGloballyDisabled = !!globalOptions.disabled;
-      // TODO(paul): Once the speedFactor is removed, we no longer need to copy each single option.
       this.rippleConfig = {
-        speedFactor: globalOptions.baseSpeedFactor,
         animation: globalOptions.animation,
         terminateOnPointerUp: globalOptions.terminateOnPointerUp,
       };

src/lib/core/ripple/ripple-renderer.ts

@@ -16,11 +16,6 @@ export type RippleConfig = {
   persistent?: boolean;
   animation?: RippleAnimationConfig;
   terminateOnPointerUp?: boolean;
-  /**
-   * @deprecated Use the `animation` property instead.
-   * @deletion-target 7.0.0
-   */
-  speedFactor?: number;
 };
 
 /**
@@ -137,7 +132,7 @@ export class RippleRenderer {
     const radius = config.radius || distanceToFurthestCorner(x, y, containerRect);
     const offsetX = x - containerRect.left;
     const offsetY = y - containerRect.top;
-    const duration = animationConfig.enterDuration / (config.speedFactor || 1);
+    const duration = animationConfig.enterDuration;
 
     const ripple = document.createElement('div');
     ripple.classList.add('mat-ripple-element');

src/lib/core/ripple/ripple.spec.ts

@@ -56,7 +56,7 @@ describe('MatRipple', () => {
       fixture = TestBed.createComponent(BasicRippleContainer);
       fixture.detectChanges();
 
-      rippleTarget = fixture.nativeElement.querySelector('[mat-ripple]');
+      rippleTarget = fixture.nativeElement.querySelector('.mat-ripple');
       rippleDirective = fixture.componentInstance.ripple;
     });
 
@@ -210,7 +210,7 @@ describe('MatRipple', () => {
       fixture = TestBed.createComponent(RippleContainerWithNgIf);
       fixture.detectChanges();
 
-      rippleTarget = fixture.debugElement.nativeElement.querySelector('[mat-ripple]');
+      rippleTarget = fixture.debugElement.nativeElement.querySelector('.mat-ripple');
 
       fixture.componentInstance.isDestroyed = true;
       fixture.detectChanges();
@@ -325,7 +325,7 @@ describe('MatRipple', () => {
       fixture = TestBed.createComponent(BasicRippleContainer);
       fixture.detectChanges();
 
-      rippleTarget = fixture.nativeElement.querySelector('[mat-ripple]');
+      rippleTarget = fixture.nativeElement.querySelector('.mat-ripple');
       rippleDirective = fixture.componentInstance.ripple;
     });
 
@@ -440,7 +440,7 @@ describe('MatRipple', () => {
       fixture = TestBed.createComponent(testComponent);
       fixture.detectChanges();
 
-      rippleTarget = fixture.nativeElement.querySelector('[mat-ripple]');
+      rippleTarget = fixture.nativeElement.querySelector('.mat-ripple');
       rippleDirective = fixture.componentInstance.ripple;
     }
 
@@ -482,41 +482,6 @@ describe('MatRipple', () => {
       expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(1);
     });
 
-    it('should support changing the baseSpeedFactor', fakeAsync(() => {
-      createTestComponent({ baseSpeedFactor: 0.5 });
-
-      dispatchMouseEvent(rippleTarget, 'mousedown');
-      dispatchMouseEvent(rippleTarget, 'mouseup');
-
-      expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(1);
-
-      // Calculates the speedFactor for the duration. Those factors needs to be inverted, because
-      // a lower speed factor, will make the duration longer. For example: 0.5 => 2x duration.
-      let fadeInFactor = 1 / 0.5;
-
-      // Calculates the duration for fading-in and fading-out the ripple.
-      tick(enterDuration * fadeInFactor + exitDuration);
-
-      expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0);
-    }));
-
-    it('should combine individual speed factor with baseSpeedFactor', fakeAsync(() => {
-      createTestComponent({ baseSpeedFactor: 0.5 });
-
-      rippleDirective.launch(0, 0, { speedFactor: 1.5 });
-
-      expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(1);
-
-      // Calculates the speedFactor for the duration. Those factors needs to be inverted, because
-      // a lower speed factor, will make the duration longer. For example: 0.5 => 2x duration.
-      let fadeInFactor = 1 / (0.5 * 1.5);
-
-      // Calculates the duration for fading-in and fading-out the ripple.
-      tick(enterDuration * fadeInFactor + exitDuration);
-
-      expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0);
-    }));
-
     it('should support changing the animation duration', fakeAsync(() => {
       createTestComponent({
         animation: {enterDuration: 100, exitDuration: 100}
@@ -567,7 +532,7 @@ describe('MatRipple', () => {
       fixture = TestBed.createComponent(BasicRippleContainer);
       fixture.detectChanges();
 
-      rippleTarget = fixture.nativeElement.querySelector('[mat-ripple]');
+      rippleTarget = fixture.nativeElement.querySelector('.mat-ripple');
       rippleDirective = fixture.componentInstance.ripple;
     });
 
@@ -585,7 +550,7 @@ describe('MatRipple', () => {
       fixture.detectChanges();
 
       controller = fixture.debugElement.componentInstance;
-      rippleTarget = fixture.debugElement.nativeElement.querySelector('[mat-ripple]');
+      rippleTarget = fixture.debugElement.nativeElement.querySelector('.mat-ripple');
     });
 
     it('sets ripple color', () => {
@@ -705,7 +670,7 @@ describe('MatRipple', () => {
 
 @Component({
   template: `
-    <div id="container" #ripple="matRipple" mat-ripple [matRippleSpeedFactor]="0"
+    <div id="container" #ripple="matRipple" matRipple
          style="position: relative; width:300px; height:200px;">
     </div>
   `,
@@ -717,8 +682,7 @@ class BasicRippleContainer {
 @Component({
   template: `
     <div id="container" style="position: relative; width:300px; height:200px;"
-      mat-ripple
-      [matRippleSpeedFactor]="0"
+      matRipple
       [matRippleTrigger]="trigger"
       [matRippleCentered]="centered"
       [matRippleRadius]="radius"
@@ -740,11 +704,11 @@ class RippleContainerWithInputBindings {
 }
 
 @Component({
-  template: `<div id="container" #ripple="matRipple" mat-ripple></div>`,
+  template: `<div id="container" #ripple="matRipple" matRipple></div>`,
 })
 class RippleContainerWithoutBindings {}
 
-@Component({ template: `<div id="container" mat-ripple [matRippleSpeedFactor]="0"
+@Component({ template: `<div id="container" matRipple
                              *ngIf="!isDestroyed"></div>` })
 class RippleContainerWithNgIf {
   @ViewChild(MatRipple) ripple: MatRipple;

src/lib/core/ripple/ripple.ts

@@ -37,15 +37,6 @@ export interface RippleGlobalOptions {
    */
   animation?: RippleAnimationConfig;
 
-  /**
-   * If set, the default duration of the fade-in animation is divided by this value. For example,
-   * setting it to 0.5 will cause the ripple fade-in animation to take twice as long.
-   * A changed speedFactor will not affect the fade-out duration of the ripples.
-   * @deprecated Use the `animation` global option instead.
-   * @deletion-target 7.0.0
-   */
-  baseSpeedFactor?: number;
-
   /**
    * Whether ripples should start fading out immediately after the mouse our touch is released. By
    * default, ripples will wait for the enter animation to complete and for mouse or touch release.
@@ -86,15 +77,6 @@ export class MatRipple implements OnInit, OnDestroy, RippleTarget {
    */
   @Input('matRippleRadius') radius: number = 0;
 
-  /**
-   * If set, the normal duration of ripple animations is divided by this value. For example,
-   * setting it to 0.5 will cause the animations to take twice as long.
-   * A changed speedFactor will not modify the fade-out duration of the ripples.
-   * @deprecated Use the [matRippleAnimation] binding instead.
-   * @deletion-target 7.0.0
-   */
-  @Input('matRippleSpeedFactor') speedFactor: number = 1;
-
   /**
    * Configuration for the ripple animation. Allows modifying the enter and exit animation
    * duration of the ripples. The animation durations will be overwritten if the
@@ -171,7 +153,6 @@ export class MatRipple implements OnInit, OnDestroy, RippleTarget {
       color: this.color,
       animation: {...this._globalOptions.animation, ...this.animation},
       terminateOnPointerUp: this._globalOptions.terminateOnPointerUp,
-      speedFactor: this.speedFactor * (this._globalOptions.baseSpeedFactor || 1),
     };
   }
 

src/lib/schematics/update/rules/ripple-v7/ripple-speed-factor.ts

@@ -0,0 +1,6 @@
+/** Converts the specified speed factor into the exact static enter duration. */
+export function convertSpeedFactorToDuration(factor: number) {
+  // Based on the numeric speed factor value that only affected the `enterDuration` we can
+  // now calculate the exact `enterDuration`. 450ms is the enter duration without factor.
+  return 450 / (factor || 1);
+}

src/lib/schematics/update/rules/ripple-v7/switchRippleSpeedFactorRule.ts

@@ -0,0 +1,114 @@
+import {ProgramAwareRuleWalker, RuleFailure, Rules} from 'tslint';
+import * as ts from 'typescript';
+import {bold, red, green} from 'chalk';
+import {convertSpeedFactorToDuration} from './ripple-speed-factor';
+
+/**
+ * Rule that walks through property assignment and switches the global `baseSpeedFactor`
+ * ripple option to the new global animation config.
+ * Also updates every class member assignment that refers to MatRipple#speedFactor.
+ */
+export class Rule extends Rules.TypedRule {
+  applyWithProgram(sourceFile: ts.SourceFile, program: ts.Program): RuleFailure[] {
+    return this.applyWithWalker(
+        new SwitchRippleSpeedFactorRule(sourceFile, this.getOptions(), program));
+  }
+}
+
+export class SwitchRippleSpeedFactorRule extends ProgramAwareRuleWalker {
+
+  /**
+   * Switches binary expressions (e.g. myRipple.speedFactor = 0.5) to the new animation config.
+   */
+  visitBinaryExpression(expression: ts.BinaryExpression) {
+    if (expression.left.kind !== ts.SyntaxKind.PropertyAccessExpression) {
+      return;
+    }
+
+    // Left side expression consists of target object and property name (e.g. myInstance.val)
+    const leftExpression = expression.left as ts.PropertyAccessExpression;
+    const targetTypeNode = this.getTypeChecker().getTypeAtLocation(leftExpression.expression);
+
+    if (!targetTypeNode.symbol) {
+      return;
+    }
+
+    const targetTypeName = targetTypeNode.symbol.getName();
+    const propertyName = leftExpression.name.getText();
+
+    if (targetTypeName === 'MatRipple' && propertyName === 'speedFactor') {
+      if (expression.right.kind === ts.SyntaxKind.NumericLiteral) {
+        const numericValue = parseFloat((expression.right as ts.NumericLiteral).text);
+        const newEnterDurationValue = convertSpeedFactorToDuration(numericValue);
+
+        // Replace the `speedFactor` property name with `animation`.
+        const propertyNameReplacement = this.createReplacement(leftExpression.name.getStart(),
+          leftExpression.name.getWidth(), 'animation');
+
+        const rightExpressionReplacement = this.createReplacement(expression.right.getStart(),
+          expression.right.getWidth(), `{enterDuration: ${newEnterDurationValue}}`);
+
+        this.addFailureAtNode(
+          expression,
+          `Found deprecated member assignment for "${bold('MatRipple')}#${red('speedFactor')}"`,
+          [propertyNameReplacement, rightExpressionReplacement]);
+      } else {
+        // In case the speed factor is dynamically calculated or passed to the assignment, we just
+        // print the failure and notify about the breaking change.
+        this.addFailureAtNode(
+          expression, `Found deprecated member assignment for "${bold('MatRipple')}#` +
+          `${red('speedFactor')}. Please manually switch from "${red('speedFactor')}" to ` +
+          `"${green('animation')}". Note that the animation property only accepts explicit ` +
+          `durations in milliseconds.`);
+      }
+    }
+  }
+
+  /**
+   * Switches a potential global option `baseSpeedFactor` to the new animation config. For this
+   * we assume that the `baseSpeedFactor` is not used in combination with individual speed factors.
+   */
+  visitPropertyAssignment(assignment: ts.PropertyAssignment) {
+    // For switching the `baseSpeedFactor` global option we expect the property assignment
+    // to be inside of a normal object literal. Custom ripple global options cannot be switched
+    // automatically.
+    if (assignment.parent.kind !== ts.SyntaxKind.ObjectLiteralExpression) {
+      return;
+    }
+
+    // The assignment consists of a name (key) and initializer (value).
+    if (assignment.name.getText() !== 'baseSpeedFactor') {
+      return;
+    }
+
+    // We could technically lazily check for the MAT_RIPPLE_GLOBAL_OPTIONS injection token to
+    // be present, but it's not right to assume that everyone sets the ripple global options
+    // immediately in the provider object (e.g. it can happen that someone just imports the
+    // config from a separate file).
+
+    if (assignment.initializer.kind === ts.SyntaxKind.NumericLiteral) {
+      const numericValue = parseFloat((assignment.initializer as ts.NumericLiteral).text);
+      const newEnterDurationValue = convertSpeedFactorToDuration(numericValue);
+
+      const keyNameReplacement = this.createReplacement(assignment.name.getStart(),
+        assignment.name.getWidth(), `animation`);
+
+      const initializerReplacement = this.createReplacement(assignment.initializer.getStart(),
+        assignment.initializer.getWidth(), `{enterDuration: ${newEnterDurationValue}}`);
+
+      this.addFailureAtNode(
+        assignment,
+        `Found deprecated property assignment for "${bold('MAT_RIPPLE_GLOBAL_OPTIONS')} -> ` +
+        `${red('baseSpeedFactor')}"`,
+        [keyNameReplacement, initializerReplacement]);
+    } else {
+      // In case the base speed factor is dynamically calculated and inside of an Angular provider,
+      // we just print the failure and notify about the breaking change.
+      this.addFailureAtNode(
+        assignment, `Found a deprecated property assignment for ` +
+        `"${bold('MAT_RIPPLE_GLOBAL_OPTIONS')} -> ${red('speedFactor')}. Please manually switch ` +
+        `from "${red('baseSpeedFactor')}" to "${green('animation')}". Note that the animation ` +
+        `property only accepts explicit durations in milliseconds.`);
+    }
+  }
+}

src/lib/schematics/update/rules/ripple-v7/switchRippleSpeedFactorTemplateRule.ts

@@ -0,0 +1,57 @@
+import {RuleFailure, Rules} from 'tslint';
+import * as ts from 'typescript';
+import {convertSpeedFactorToDuration} from './ripple-speed-factor';
+import {ExternalResource} from '../../tslint/component-file';
+import {ComponentWalker} from '../../tslint/component-walker';
+import {red, green} from 'chalk';
+
+/** Regular expression that matches [matRippleSpeedFactor]="$NUMBER" in templates. */
+const speedFactorNumberRegex = /\[matRippleSpeedFactor]="(\d+(?:\.\d+)?)"/g;
+
+/** Regular expression that matches [matRippleSpeedFactor]="$NOT_A_NUMBER" in templates. */
+const speedFactorNotParseable = /\[matRippleSpeedFactor]="(?!\d+(?:\.\d+)?")(.*)"/g;
+
+/**
+ * Rule that walks through every inline or external template and updates the deprecated
+ * [matRippleSpeedFactor] to [matRippleAnimation].
+ */
+export class Rule extends Rules.AbstractRule {
+  apply(sourceFile: ts.SourceFile): RuleFailure[] {
+    return this.applyWithWalker(
+        new SwitchRippleSpeedFactorTemplateRule(sourceFile, this.getOptions()));
+  }
+}
+
+export class SwitchRippleSpeedFactorTemplateRule extends ComponentWalker {
+
+  visitInlineTemplate(template: ts.StringLiteral) {
+    this._checkTemplateContent(template);
+  }
+
+  visitExternalTemplate(template: ExternalResource) {
+    this._checkTemplateContent(template);
+  }
+
+  private _checkTemplateContent(template: ExternalResource | ts.StringLiteral) {
+    const startPos = template.getStart();
+    const templateText = template.getText();
+
+    let match: RegExpMatchArray | null;
+
+    while ((match = speedFactorNumberRegex.exec(templateText)) !== null) {
+      const newEnterDuration = convertSpeedFactorToDuration(parseFloat(match[1]));
+      const fix = this.createReplacement(startPos + match.index!, match[0].length,
+        `[matRippleAnimation]="{enterDuration: ${newEnterDuration}}"`);
+
+      this.addFailureAt(startPos + match.index!, match[0].length,
+        'Detected deprecated [matRippleSpeedFactor] input binding with readable number.', fix);
+    }
+
+    while ((match = speedFactorNotParseable.exec(templateText)) !== null) {
+      this.addFailureAt(startPos + match.index!, match[0].length,
+        `Detected deprecated ${red('[matRippleSpeedFactor]')} input binding with non-parseable ` +
+        `value. Please switch manually to ${green('[matRippleAnimation]')}. Note that the ` +
+        `animation config only accepts explicit durations in milliseconds.`);
+    }
+  }
+}