update(ripple): allow passing ripple config only (#9760)

Adds a method overload to the `launch` method of the `MatRipple` class. This should make it possible for developers to just pass in a configuration without coordinates that will be ignored (e.g. `launch(0, 0, {centered: true});`).

Author: devversion

src/lib/core/ripple/ripple.md

@@ -46,7 +46,7 @@ class MyComponent {
 
   /** Shows a centered and persistent ripple. */
   launchRipple() {
-    const rippleRef = this.ripple.launch(0, 0, {
+    const rippleRef = this.ripple.launch({
       persistent: true,
       centered: true
     });
@@ -57,13 +57,21 @@ class MyComponent {
 }
 ```
 
-In the example above, the `x` and `y` parameters will be ignored, because the `centered`
-ripple option has been set to `true`.
+In the example above, no specific coordinates have been passed, because the `centered`
+ripple option has been set to `true` and the coordinates would not matter.
 
 Ripples that are being dispatched programmatically can be launched with the `persistent` option.
 This means that the ripples will not fade out automatically, and need to be faded out using
 the `RippleRef` (*useful for focus indicators*).
 
+In case, developers want to launch ripples at specific coordinates within the element, the
+`launch()` method also accepts `x` and `y` coordinates as parameters. Those coordinates
+are relative to the ripple container element.
+
+```ts
+const rippleRef = this.ripple.launch(10, 10, {persistent: true});
+```
+
 ### Global options
 
 Developers are able to specify options for all ripples inside of their application.

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

@@ -390,6 +390,24 @@ describe('MatRipple', () => {
 
      expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0);
    }));
+
+   it('should allow passing only a configuration', fakeAsync(() => {
+     expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0);
+
+     const rippleRef = rippleDirective.launch({persistent: true});
+
+     expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(1);
+
+     tick(enterDuration + exitDuration);
+
+     expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(1);
+
+     rippleRef.fadeOut();
+
+     tick(exitDuration);
+
+     expect(rippleTarget.querySelectorAll('.mat-ripple-element').length).toBe(0);
+   }));
   });
 
   describe('global ripple options', () => {

src/lib/core/ripple/ripple.ts

@@ -150,11 +150,6 @@ export class MatRipple implements OnInit, OnDestroy, RippleTarget {
     this._rippleRenderer._removeTriggerEvents();
   }
 
-  /** Launches a manual ripple at the specified position. */
-  launch(x: number, y: number, config?: RippleConfig): RippleRef {
-    return this._rippleRenderer.fadeInRipple(x, y, {...this.rippleConfig, ...config});
-  }
-
   /** Fades out all currently showing ripple elements. */
   fadeOutAll() {
     this._rippleRenderer.fadeOutAll();
@@ -183,5 +178,28 @@ export class MatRipple implements OnInit, OnDestroy, RippleTarget {
       this._rippleRenderer.setupTriggerEvents(this.trigger);
     }
   }
+
+  /**
+   * Launches a manual ripple using the specified ripple configuration.
+   * @param config Configuration for the manual ripple.
+   */
+  launch(config: RippleConfig): RippleRef;
+
+  /**
+   * Launches a manual ripple at the specified coordinates within the element.
+   * @param x Coordinate within the element, along the X axis at which to fade-in the ripple.
+   * @param y Coordinate within the element, along the Y axis at which to fade-in the ripple.
+   * @param config Optional ripple configuration for the manual ripple.
+   */
+  launch(x: number, y: number, config?: RippleConfig): RippleRef;
+
+  /** Launches a manual ripple at the specified coordinated or just by the ripple config. */
+  launch(configOrX: number | RippleConfig, y: number = 0, config?: RippleConfig): RippleRef {
+    if (typeof configOrX === 'number') {
+      return this._rippleRenderer.fadeInRipple(configOrX, y, {...this.rippleConfig, ...config});
+    } else {
+      return this._rippleRenderer.fadeInRipple(0, 0, {...this.rippleConfig, ...configOrX});
+    }
+  }
 }