fix(types): Improve Typescript coverage (#8148)

src/js/big-play-button.js

@@ -5,6 +5,10 @@ import Button from './button.js';
 import Component from './component.js';
 import {isPromise, silencePromise} from './utils/promise';
 
+/**
+ *  @typedef {import('../event-target').Event} Event
+ */
+
 /**
  * The initial play button that shows before the video has played. The hiding of the
  * `BigPlayButton` get done via CSS and `Player` states.
@@ -34,7 +38,7 @@ class BigPlayButton extends Button {
    * This gets called when a `BigPlayButton` "clicked". See {@link ClickableComponent}
    * for more detailed information on what a click can be.
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The `keydown`, `tap`, or `click` event that caused this function to be
    *        called.
    *

src/js/button.js

@@ -104,7 +104,7 @@ class Button extends ClickableComponent {
    * This gets called when a `Button` has focus and `keydown` is triggered via a key
    * press.
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The event that caused this function to get called.
    *
    * @listens keydown

src/js/clickable-component.js

@@ -6,6 +6,10 @@ import * as Dom from './utils/dom.js';
 import log from './utils/log.js';
 import keycode from 'keycode';
 
+/**
+ * @typedef { import('./player').default } Player
+ */
+
 /**
  * Component which is clickable or keyboard actionable, but is not a
  * native HTML button.
@@ -212,7 +216,7 @@ class ClickableComponent extends Component {
    * Event handler that is called when a `ClickableComponent` receives a
    * `click` or `tap` event.
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The `tap` or `click` event that caused this function to be called.
    *
    * @listens tap
@@ -231,7 +235,7 @@ class ClickableComponent extends Component {
    *
    * By default, if the key is Space or Enter, it will trigger a `click` event.
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The `keydown` event that caused this function to be called.
    *
    * @listens keydown

src/js/close-button.js

@@ -5,6 +5,10 @@ import Button from './button';
 import Component from './component';
 import keycode from 'keycode';
 
+/**
+ * @typedef { import('./player').default } Player
+ */
+
 /**
  * The `CloseButton` is a `{@link Button}` that fires a `close` event when
  * it gets clicked.
@@ -42,7 +46,7 @@ class CloseButton extends Button {
    * {@link ClickableComponent#handleClick} for more information on when
    * this will be triggered
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The `keydown`, `tap`, or `click` event that caused this function to be
    *        called.
    *
@@ -56,7 +60,7 @@ class CloseButton extends Button {
      * Triggered when the a `CloseButton` is clicked.
      *
      * @event CloseButton#close
-     * @type {EventTarget~Event}
+     * @type {Event}
      *
      * @property {boolean} [bubbles=false]
      *           set to false so that the close event does not
@@ -70,7 +74,7 @@ class CloseButton extends Button {
    *
    * By default, if the key is Esc, it will trigger a `click` event.
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The `keydown` event that caused this function to be called.
    *
    * @listens keydown

src/js/component.js

@@ -13,6 +13,11 @@ import {toTitleCase, toLowerCase} from './utils/str.js';
 import {merge} from './utils/obj.js';
 import keycode from 'keycode';
 
+/**
+ * @typedef { import('./player').default } Player
+ * @typedef { import('./event-target').Event} Event
+*/
+
 /**
  * Base class for all UI Components.
  * Components are UI objects which represent both a javascript object and an element
@@ -27,7 +32,7 @@ class Component {
    * A callback that is called when a component is ready. Does not have any
    * parameters and any callback value will be ignored.
    *
-   * @callback Component~ReadyCallback
+   * @callback ReadyCallback
    * @this Component
    */
 
@@ -48,7 +53,7 @@ class Component {
    * @param  {string} [options.className]
    *         A class or space separated list of classes to add the component
    *
-   * @param {Component~ReadyCallback} [ready]
+   * @param {ReadyCallback} [ready]
    *        Function that gets called when the `Component` is ready.
    */
   constructor(player, options, ready) {
@@ -95,6 +100,12 @@ class Component {
       options.className.split(' ').forEach(c => this.addClass(c));
     }
 
+    // Remove the placeholder event methods. If the component is evented, the
+    // real methods are added next
+    ['on', 'off', 'one', 'any', 'trigger'].forEach(fn => {
+      this[fn] = undefined;
+    });
+
     // if evented is anything except false, we want to mixin in evented
     if (options.evented !== false) {
       // Make this an evented object and use `el_`, if available, as its event bus
@@ -130,6 +141,79 @@ class Component {
 
   }
 
+  // `on`, `off`, `one`, `any` and `trigger` are here so tsc includes them in definitions.
+  // They are replaced or removed in the constructor
+
+  /**
+   * Adds an `event listener` to an instance of an `EventTarget`. An `event listener` is a
+   * function that will get called when an event with a certain name gets triggered.
+   *
+   * @param {string|string[]} type
+   *        An event name or an array of event names.
+   *
+   * @param {Function} fn
+   *        The function to call with `EventTarget`s
+   */
+  on(type, fn) {}
+
+  /**
+   * Removes an `event listener` for a specific event from an instance of `EventTarget`.
+   * This makes it so that the `event listener` will no longer get called when the
+   * named event happens.
+   *
+   * @param {string|string[]} type
+   *        An event name or an array of event names.
+   *
+   * @param {Function} fn
+   *        The function to remove.
+   */
+  off(type, fn) {}
+
+  /**
+   * This function will add an `event listener` that gets triggered only once. After the
+   * first trigger it will get removed. This is like adding an `event listener`
+   * with {@link EventTarget#on} that calls {@link EventTarget#off} on itself.
+   *
+   * @param {string|string[]} type
+   *        An event name or an array of event names.
+   *
+   * @param {Function} fn
+   *        The function to be called once for each event name.
+   */
+  one(type, fn) {}
+
+  /**
+   * This function will add an `event listener` that gets triggered only once and is
+   * removed from all events. This is like adding an array of `event listener`s
+   * with {@link EventTarget#on} that calls {@link EventTarget#off} on all events the
+   * first time it is triggered.
+   *
+   * @param {string|string[]} type
+   *        An event name or an array of event names.
+   *
+   * @param {Function} fn
+   *        The function to be called once for each event name.
+   */
+  any(type, fn) {}
+
+  /**
+   * This function causes an event to happen. This will then cause any `event listeners`
+   * that are waiting for that event, to get called. If there are no `event listeners`
+   * for an event then nothing will happen.
+   *
+   * If the name of the `Event` that is being triggered is in `EventTarget.allowedEvents_`.
+   * Trigger will also call the `on` + `uppercaseEventName` function.
+   *
+   * Example:
+   * 'click' is in `EventTarget.allowedEvents_`, so, trigger will attempt to call
+   * `onClick` if it exists.
+   *
+   * @param {string|Event|Object} event
+   *        The name of the event, an `Event`, or an object with a key of type set to
+   *        an event name.
+   */
+  trigger(event) {}
+
   /**
    * Dispose of the `Component` and all child components.
    *
@@ -153,7 +237,7 @@ class Component {
      * Triggered when a `Component` is disposed.
      *
      * @event Component#dispose
-     * @type {EventTarget~Event}
+     * @type {Event}
      *
      * @property {boolean} [bubbles=false]
      *           set to false so that the dispose event does not
@@ -700,7 +784,7 @@ class Component {
    * Different from event listeners in that if the ready event has already happened
    * it will trigger the function immediately.
    *
-   * @param {Component~ReadyCallback} fn
+   * @param {ReadyCallback} fn
    *        Function that gets called when the `Component` is ready.
    *
    * @return {Component}
@@ -751,7 +835,7 @@ class Component {
        * Triggered when a `Component` is ready.
        *
        * @event Component#ready
-       * @type {EventTarget~Event}
+       * @type {Event}
        */
       this.trigger('ready');
     }, 1);
@@ -1033,7 +1117,7 @@ class Component {
          * Triggered when a component is resized.
          *
          * @event Component#componentresize
-         * @type {EventTarget~Event}
+         * @type {Event}
          */
         this.trigger('componentresize');
       }
@@ -1169,7 +1253,7 @@ class Component {
    * When this Component receives a `keydown` event which it does not process,
    *  it passes the event to the Player for handling.
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The `keydown` event that caused this function to be called.
    */
   handleKeyDown(event) {
@@ -1190,7 +1274,7 @@ class Component {
    * delegates to `handleKeyDown`. This means anyone calling `handleKeyPress`
    * will not see their method calls stop working.
    *
-   * @param {EventTarget~Event} event
+   * @param {Event} event
    *        The event that caused this function to be called.
    */
   handleKeyPress(event) {
@@ -1283,7 +1367,7 @@ class Component {
            * Triggered when a `Component` is tapped.
            *
            * @event Component#tap
-           * @type {EventTarget~Event}
+           * @type {Event}
            */
           this.trigger('tap');
           // It may be good to copy the touchend event object and change the

src/js/control-bar/audio-track-controls/audio-track-menu-item.js

@@ -5,6 +5,10 @@ import MenuItem from '../../menu/menu-item.js';
 import Component from '../../component.js';
 import * as Dom from '../../utils/dom.js';
 
+/**
+ * @typedef { import('../../player').default } Player
+ */
+
 /**
  * An {@link AudioTrack} {@link MenuItem}
  *
@@ -68,7 +72,7 @@ class AudioTrackMenuItem extends MenuItem {
    * This gets called when an `AudioTrackMenuItem is "clicked". See {@link ClickableComponent}
    * for more detailed information on what a click can be.
    *
-   * @param {EventTarget~Event} [event]
+   * @param {Event} [event]
    *        The `keydown`, `tap`, or `click` event that caused this function to be
    *        called.
    *
@@ -102,7 +106,7 @@ class AudioTrackMenuItem extends MenuItem {
   /**
    * Handle any {@link AudioTrack} change.
    *
-   * @param {EventTarget~Event} [event]
+   * @param {Event} [event]
    *        The {@link AudioTrackList#change} event that caused this to run.
    *
    * @listens AudioTrackList#change

src/js/control-bar/fullscreen-toggle.js

@@ -5,6 +5,10 @@ import Button from '../button.js';
 import Component from '../component.js';
 import document from 'global/document';
 
+/**
+ * @typedef { import('./player').default } Player
+ */
+
 /**
  * Toggle fullscreen video
  *
@@ -43,7 +47,7 @@ class FullscreenToggle extends Button {
   /**
    * Handles fullscreenchange on the player and change control text accordingly.
    *
-   * @param {EventTarget~Event} [event]
+   * @param {Event} [event]
    *        The {@link Player#fullscreenchange} event that caused this function to be
    *        called.
    *
@@ -61,7 +65,7 @@ class FullscreenToggle extends Button {
    * This gets called when an `FullscreenToggle` is "clicked". See
    * {@link ClickableComponent} for more detailed information on what a click can be.
    *
-   * @param {EventTarget~Event} [event]
+   * @param {Event} [event]
    *        The `keydown`, `tap`, or `click` event that caused this function to be
    *        called.
    *

src/js/control-bar/live-display.js

@@ -5,6 +5,10 @@ import Component from '../component';
 import * as Dom from '../utils/dom.js';
 import document from 'global/document';
 
+/**
+ * @typedef { import('./player').default } Player
+ */
+
 // TODO - Future make it click to snap to live
 
 /**
@@ -67,7 +71,7 @@ class LiveDisplay extends Component {
    * Check the duration to see if the LiveDisplay should be showing or not. Then show/hide
    * it accordingly
    *
-   * @param {EventTarget~Event} [event]
+   * @param {Event} [event]
    *        The {@link Player#durationchange} event that caused this function to run.
    *
    * @listens Player#durationchange

src/js/control-bar/mute-toggle.js

@@ -7,6 +7,10 @@ import * as Dom from '../utils/dom.js';
 import checkMuteSupport from './volume-control/check-mute-support';
 import * as browser from '../utils/browser.js';
 
+/**
+ * @typedef { import('./player').default } Player
+ */
+
 /**
  * A button component for muting the audio.
  *
@@ -46,7 +50,7 @@ class MuteToggle extends Button {
    * This gets called when an `MuteToggle` is "clicked". See
    * {@link ClickableComponent} for more detailed information on what a click can be.
    *
-   * @param {EventTarget~Event} [event]
+   * @param {Event} [event]
    *        The `keydown`, `tap`, or `click` event that caused this function to be
    *        called.
    *
@@ -71,7 +75,7 @@ class MuteToggle extends Button {
    * Update the `MuteToggle` button based on the state of `volume` and `muted`
    * on the player.
    *
-   * @param {EventTarget~Event} [event]
+   * @param {Event} [event]
    *        The {@link Player#loadstart} event if this function was called
    *        through an event.
    *