Make `ListenerCollection.add` smarter

Enable the `ListenerCollection.add` method to know the specific type of
event that a listener will receive, based on the event target and event
name. This simplifies usage by removing the need to cast the argument in
most cases.

The implementation relies on the target having an `on${eventName}`
property from which the event type can be extracted. If it doesn't, it
will fall back to `Event`.

src/annotator/guest.js

@@ -252,7 +252,7 @@ export class Guest {
     };
 
     this._listeners.add(this.element, 'mouseup', event => {
-      const { target, metaKey, ctrlKey } = /** @type {MouseEvent} */ (event);
+      const { target, metaKey, ctrlKey } = event;
       const tags = annotationsAt(/** @type {Element} */ (target));
       if (tags.length && this._highlightsVisible) {
         const toggle = metaKey || ctrlKey;

src/shared/listener-collection.js

@@ -5,6 +5,23 @@
  * @prop {(event: Event) => void} listener
  */
 
+/**
+ * Return the event type that a listener will receive.
+ *
+ * For example `EventType<HTMLElement, 'keydown'>` evaluates to `KeyboardEvent`.
+ *
+ * The event type is extracted from the target's `on${Type}` property (eg.
+ * `HTMLElement.onkeydown` here) If there is no such property, the type defaults
+ * to `Event`.
+ *
+ * @template {EventTarget} Target
+ * @template {string} Type
+ * @typedef {`on${Type}` extends keyof Target ?
+ *   Target[`on${Type}`] extends ((...args: any[]) => void)|null ?
+ *     Parameters<NonNullable<Target[`on${Type}`]>>[0]
+ *  : Event : Event} EventType
+ */
+
 /**
  * Utility that provides a way to conveniently remove a set of DOM event
  * listeners when they are no longer needed.
@@ -18,20 +35,31 @@ export class ListenerCollection {
   /**
    * Add a listener and return an ID that can be used to remove it later
    *
-   * @param {Listener['eventTarget']} eventTarget
-   * @param {Listener['eventType']} eventType
-   * @param {Listener['listener']} listener
+   * @template {string} Type
+   * @template {EventTarget} Target
+   * @param {Target} eventTarget
+   * @param {Type} eventType
+   * @param {(event: EventType<Target, Type>) => void} listener
    * @param {AddEventListenerOptions} [options]
    */
   add(eventTarget, eventType, listener, options) {
-    eventTarget.addEventListener(eventType, listener, options);
+    eventTarget.addEventListener(
+      eventType,
+      /** @type {EventListener} */ (listener),
+      options
+    );
     const symbol = Symbol();
-    this._listeners.set(symbol, { eventTarget, eventType, listener });
+    this._listeners.set(symbol, {
+      eventTarget,
+      eventType,
+      // eslint-disable-next-line object-shorthand
+      listener: /** @type {EventListener} */ (listener),
+    });
     return symbol;
   }
 
   /**
-   * Remove a listener using a listenerId
+   * Remove a specific listener.
    *
    * @param {Symbol} listenerId
    */

src/shared/messaging/port-finder.js

@@ -94,7 +94,7 @@ export class PortFinder {
       }, MAX_WAIT_FOR_PORT);
 
       const listenerId = this._listeners.add(window, 'message', event => {
-        const { data, ports } = /** @type {MessageEvent} */ (event);
+        const { data, ports } = event;
         if (
           isMessageEqual(data, {
             frame1: this._source,

src/shared/messaging/port-provider.js

@@ -135,9 +135,9 @@ export class PortProvider {
       sendError(new Error(message), errorContext);
     };
 
-    /** @param {Event} event */
+    /** @param {MessageEvent} event */
     const handleRequest = event => {
-      const { data, origin, source } = /** @type {MessageEvent} */ (event);
+      const { data, origin, source } = event;
 
       if (!isMessage(data) || data.type !== 'request') {
         // If this does not look like a message intended for us, ignore it.

src/shared/messaging/port-rpc.js

@@ -230,9 +230,7 @@ export class PortRPC {
    */
   connect(port) {
     this._port = port;
-    this._listeners.add(port, 'message', event =>
-      this._handle(/** @type {MessageEvent} */ (event))
-    );
+    this._listeners.add(port, 'message', event => this._handle(event));
     port.start();
     sendCall(port, 'connect');
 

src/sidebar/services/frame-sync.js

@@ -392,7 +392,7 @@ export class FrameSyncService {
 
     // Listen for guests connecting to the sidebar.
     this._listeners.add(hostPort, 'message', event => {
-      const { data, ports } = /** @type {MessageEvent} */ (event);
+      const { data, ports } = event;
       if (
         isMessageEqual(data, {
           frame1: 'guest',