feat: playerresize event on Player dimension API calls (#4800)

Trigger a `playerresize` event when `width()`, `height()`, or `dimensions()` is called.

First part of #4629.

src/js/player.js

@@ -661,11 +661,14 @@ class Player extends Component {
    * @param {number} [value]
    *        The value to set the `Player`'s width to.
    *
+   * @param {boolean} [skipListeners]
+   *        Skip the playerresize event trigger
+   *
    * @return {number}
    *         The current width of the `Player` when getting.
    */
-  width(value) {
-    return this.dimension('width', value);
+  width(value, skipListeners) {
+    return this.dimension('width', value, skipListeners);
   }
 
   /**
@@ -675,16 +678,21 @@ class Player extends Component {
    * @param {number} [value]
    *        The value to set the `Player`'s heigth to.
    *
+   * @param {boolean} [skipListeners]
+   *        Skip the playerresize event trigger
+   *
    * @return {number}
    *         The current height of the `Player` when getting.
    */
-  height(value) {
-    return this.dimension('height', value);
+  height(value, skipListeners) {
+    return this.dimension('height', value, skipListeners);
   }
 
   /**
    * A getter/setter for the `Player`'s width & height.
    *
+   * @fires Player#playerresize
+   *
    * @param {string} dimension
    *        This string can be:
    *        - 'width'
@@ -693,10 +701,13 @@ class Player extends Component {
    * @param {number} [value]
    *        Value for dimension specified in the first argument.
    *
+   * @param {boolean} [skipListeners]
+   *        Skip the playerresize event trigger
+   *
    * @return {number}
    *         The dimension arguments value when getting (width/height).
    */
-  dimension(dimension, value) {
+  dimension(dimension, value, skipListeners) {
     const privDimension = dimension + '_';
 
     if (value === undefined) {
@@ -719,6 +730,17 @@ class Player extends Component {
 
     this[privDimension] = parsedVal;
     this.updateStyleEl_();
+
+    // skipListeners allows us to avoid triggering the resize event when setting both width and height
+    if (this.isReady_ && !skipListeners) {
+      /**
+       * Triggered when the player is resized.
+       *
+       * @event Player#playerresize
+       * @type {EventTarget~Event}
+       */
+      this.trigger('playerresize');
+    }
   }
 
   /**

test/unit/player.test.js

@@ -1709,3 +1709,32 @@ QUnit.test('player.duration() sets the value of player.cache_.duration', functio
   player.duration(200);
   assert.equal(player.duration(), 200, 'duration() set and get integer duration value');
 });
+
+QUnit.test('should fire playerresize when player is resized', function(assert) {
+  assert.expect(2);
+
+  const player = TestHelpers.makePlayer();
+
+  player.on('playerresize', function() {
+    assert.ok(true, 'playerresize fired');
+  });
+
+  player.width(400);
+  player.height(300);
+
+  player.dispose();
+});
+
+QUnit.test('should fire playerresize exactly once for a two-dimensional resize', function(assert) {
+  assert.expect(1);
+
+  const player = TestHelpers.makePlayer();
+
+  player.on('playerresize', function() {
+    assert.ok(true, 'playerresize fired once');
+  });
+
+  player.dimensions(400, 300);
+
+  player.dispose();
+});