refactor: add currentTarget back to regular listeners, add childTarget to onChild listeners (@fehmer) (monkeytypegame#7273)

fehmer · Miodec · web-flow · commit bd3cd75c9470 · 2025-12-20T13:41:11.000+01:00
rework `onChild` to behave mostly like jQuery `.on` with selector.

- we remove `currentTarget` from the `onChild` event handler because
native events and jQuery events have different values for it
- the jQuery `currentTarget` is available with `childTarget` in our
events

---------

Co-authored-by: Miodec &lt;jack@monkeytype.com&gt;
diff --git a/frontend/__tests__/setup-jsdom.ts b/frontend/__tests__/setup-jsdom.ts
@@ -0,0 +1,6 @@
+import $ from "jquery";
+
+//@ts-expect-error add to global
+global["$"] = $;
+//@ts-expect-error add to global
+global["jQuery"] = $;
diff --git a/frontend/__tests__/setup-tests.ts b/frontend/__tests__/setup-tests.ts
@@ -2,9 +2,9 @@ import { vi } from "vitest";
 import $ from "jquery";
 import { ElementWithUtils } from "../src/ts/utils/dom";
 
-//@ts-expect-error add to globl
+//@ts-expect-error add to global
 global["$"] = $;
-//@ts-expect-error add to globl
+//@ts-expect-error add to global
 global["jQuery"] = $;
 
 vi.mock("../src/ts/constants/env-config", () => ({
diff --git a/frontend/__tests__/tsconfig.json b/frontend/__tests__/tsconfig.json
@@ -6,5 +6,5 @@
     "noEmit": true
   },
   "files": ["vitest.d.ts"],
-  "include": ["./**/*.spec.ts", "./setup-tests.ts"]
+  "include": ["./**/*.spec.ts", "./**/*.jsdom-spec.ts", "./setup-tests.ts"]
 }
diff --git a/frontend/__tests__/utils/dom.jsdom-spec.ts b/frontend/__tests__/utils/dom.jsdom-spec.ts
@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { screen } from "@testing-library/dom";
+import { userEvent } from "@testing-library/user-event";
+import { qs } from "../../src/ts/utils/dom";
+
+describe("dom", () => {
+  describe("ElementWithUtils", () => {
+    describe("onChild", () => {
+      const handler = vi.fn();
+
+      function registerOnChild(event: string, selector: string): void {
+        const parent = qs("#parent");
+        parent?.onChild(event, selector, (e) =>
+          handler({
+            target: e.target,
+            childTarget: e.childTarget,
+            //@ts-expect-error will be added later, check TODO on the ChildEvent
+            currentTarget: e.currentTarget,
+          }),
+        );
+      }
+
+      beforeEach(() => {
+        handler.mockReset();
+
+        document.body.innerHTML = "";
+        const root = document.createElement("div");
+
+        root.innerHTML = `
+          <div id="parent" data-testid="parent">
+            <section id="decoy">
+            <div id="mid1" data-testid="mid1" class="middle">
+                <div id="inner1" class="inner">test</div>
+                <div id="inner2" data-testid="inner2" class="inner">
+                  test
+                  <button id="button" data-testid="button">click</button>
+                </div>
+            </div>
+            <div id="mid2" class="middle">
+                <div id="inner3" class="inner">test</div>
+                <div id="inner4" class="inner">test</div>
+            </div>
+            </section>
+        </div>
+        `;
+        document.body.appendChild(root);
+      });
+
+      it("should not fire when parent element is clicked", async () => {
+        //GIVEN
+        registerOnChild("click", "div");
+
+        //WHEN
+        await userEvent.click(screen.getByTestId("parent"));
+
+        //THEN
+        expect(handler).not.toHaveBeenCalled();
+      });
+
+      it("should fire when selector is clicked", async () => {
+        //GIVEN
+        registerOnChild("click", "div");
+
+        //WHEN
+        const clickTarget = screen.getByTestId("mid1");
+        await userEvent.click(clickTarget);
+
+        //THEN
+        expect(handler).toHaveBeenCalledWith(
+          expect.objectContaining({
+            target: clickTarget,
+            childTarget: clickTarget,
+            currentTarget: screen.getByTestId("parent"),
+          }),
+        );
+      });
+
+      it("should fire when child of selector is clicked", async () => {
+        //GIVEN
+        registerOnChild("click", "div.middle");
+
+        //WHEN
+        const selectorTarget = screen.getByTestId("mid1");
+        const clickTarget = screen.getByTestId("button");
+        await userEvent.click(clickTarget);
+
+        //THEN
+        expect(handler).toHaveBeenCalledWith(
+          expect.objectContaining({
+            target: clickTarget,
+            childTarget: selectorTarget,
+            currentTarget: screen.getByTestId("parent"),
+          }),
+        );
+      });
+
+      it("should fire on each element matching the selector from the child up to the parent", async () => {
+        //GIVEN
+        registerOnChild("click", "div.middle, div.inner");
+
+        //WHEN
+        let clickTarget = screen.getByTestId("button");
+        await userEvent.click(clickTarget);
+
+        //THEN
+
+        //This is the same behavior as jQuery `.on` with selector.
+        //The handler will be called two times,
+        //It does NOT call on the <section> or the parent element itself
+        expect(handler).toHaveBeenCalledTimes(2);
+
+        //First call is for childTarget inner2 (grand child of parent)
+        expect(handler).toHaveBeenNthCalledWith(
+          1,
+          expect.objectContaining({
+            target: clickTarget,
+            childTarget: screen.getByTestId("inner2"),
+            currentTarget: screen.getByTestId("parent"),
+          }),
+        );
+
+        //Second call is for childTarget mid1 (child of parent)
+        expect(handler).toHaveBeenNthCalledWith(
+          2,
+          expect.objectContaining({
+            target: clickTarget,
+            childTarget: screen.getByTestId("mid1"),
+            currentTarget: screen.getByTestId("parent"),
+          }),
+        );
+
+        //WHEN click on mid1 handler is only called one time
+        handler.mockReset();
+        clickTarget = screen.getByTestId("mid1");
+        await userEvent.click(clickTarget);
+
+        //THEN
+        expect(handler).toHaveBeenCalledTimes(1);
+
+        expect(handler).toHaveBeenCalledWith(
+          expect.objectContaining({
+            target: clickTarget,
+            childTarget: clickTarget,
+            currentTarget: screen.getByTestId("parent"),
+          }),
+        );
+      });
+    });
+  });
+});
diff --git a/frontend/package.json b/frontend/package.json
@@ -61,6 +61,8 @@
     "@fortawesome/fontawesome-free": "5.15.4",
     "@monkeytype/oxlint-config": "workspace:*",
     "@monkeytype/typescript-config": "workspace:*",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/user-event": "14.6.1",
     "@types/canvas-confetti": "1.4.3",
     "@types/chartjs-plugin-trendline": "1.0.1",
     "@types/damerau-levenshtein": "1.0.0",
diff --git a/frontend/src/ts/elements/input-validation.ts b/frontend/src/ts/elements/input-validation.ts
@@ -8,7 +8,7 @@ import {
 } from "@monkeytype/schemas/configs";
 import Config, { setConfig } from "../config";
 import * as Notifications from "../elements/notifications";
-import { DomUtilsEvent, ElementWithUtils } from "../utils/dom";
+import { ElementWithUtils } from "../utils/dom";
 
 export type ValidationResult = {
   status: "checking" | "success" | "failed" | "warning";
@@ -60,7 +60,7 @@ export function createInputEventHandler<T>(
   callback: (result: ValidationResult) => void,
   validation: Validation<T>,
   inputValueConvert?: (val: string) => T,
-): (e: DomUtilsEvent) => Promise<void> {
+): (e: Event) => Promise<void> {
   let callIsValid =
     validation.isValid !== undefined
       ? debounceIfNeeded(
diff --git a/frontend/src/ts/utils/dom.ts b/frontend/src/ts/utils/dom.ts
@@ -105,11 +105,18 @@ type ElementWithValue =
   | HTMLTextAreaElement
   | HTMLSelectElement;
 
-export type DomUtilsEvent<T extends Event = Event> = Omit<T, "currentTarget">;
+//TODO: after the migration from jQuery to dom-utils we might want to add currentTarget back to the event object, if we have a use-case for it.
+// For now we remove it because currentTarget is not the same element when using dom-utils intead of jQuery to get compile errors.
+export type OnChildEvent<T extends Event = Event> = Omit<T, "currentTarget"> & {
+  /**
+   * target element matching the selector. This emulates the behavior of `currentTarget` in jQuery events registered with `.on(events, selector, handler)`
+   */
+  childTarget: EventTarget | null;
+};
 
-type DomUtilsEventListenerOrEventListenerObject =
-  | { (evt: DomUtilsEvent): void }
-  | { handleEvent(object: DomUtilsEvent): void };
+type OnChildEventListenerOrEventListenerObject =
+  | { (evt: OnChildEvent): void }
+  | { handleEvent(object: OnChildEvent): void };
 
 export class ElementWithUtils<T extends HTMLElement = HTMLElement> {
   /**
@@ -244,56 +251,80 @@ export class ElementWithUtils<T extends HTMLElement = HTMLElement> {
    */
   on<K extends keyof HTMLElementEventMap>(
     event: K,
-    handler: (this: T, ev: DomUtilsEvent<HTMLElementEventMap[K]>) => void,
+    handler: (this: T, ev: HTMLElementEventMap[K]) => void,
   ): this;
-  on(event: string, handler: DomUtilsEventListenerOrEventListenerObject): this;
+  on(event: string, handler: EventListenerOrEventListenerObject): this;
   on(
     event: keyof HTMLElementEventMap | string,
     handler:
-      | DomUtilsEventListenerOrEventListenerObject
-      | ((this: T, ev: DomUtilsEvent) => void),
+      | EventListenerOrEventListenerObject
+      | ((this: T, ev: Event) => void),
   ): this {
     // this type was some AI magic but if it works it works
     this.native.addEventListener(
       event,
-      handler as DomUtilsEventListenerOrEventListenerObject,
+      handler as EventListenerOrEventListenerObject,
     );
     return this;
   }
 
   /**
-   * Attach an event listener to child elements matching the query.
+   * Attach an event listener to child elements matching the selector.
    * Useful for dynamically added elements.
+   *
+   * The handler is not called when the event occurs directly on the bound element, but only for descendants (inner elements)
+   * that match the selector. Bubbles the event from the event target up to the element where the handler is attached
+   * (i.e., innermost to outermost element) and runs the handler for any elements along that path matching the selector.
    */
   onChild<K extends keyof HTMLElementEventMap>(
     event: K,
-    query: string,
+    /**
+     * A selector string to filter the descendants of the selected elements that will call the handler.
+     */
+    selector: string,
     handler: (
       this: HTMLElement,
-      ev: DomUtilsEvent<HTMLElementEventMap[K]>,
+      ev: OnChildEvent<HTMLElementEventMap[K]>,
     ) => void,
   ): this;
   onChild(
     event: string,
-    query: string,
-    handler: DomUtilsEventListenerOrEventListenerObject,
+    /**
+     * A selector string to filter the descendants of the selected elements that will call the handler.
+     */
+    selector: string,
+    handler: OnChildEventListenerOrEventListenerObject,
   ): this;
   onChild(
     event: keyof HTMLElementEventMap | string,
-    query: string,
+    /**
+     * A selector string to filter the descendants of the selected elements that will call the handler.
+     */
+    selector: string,
     handler:
-      | DomUtilsEventListenerOrEventListenerObject
-      | ((this: HTMLElement, ev: DomUtilsEvent) => void),
+      | OnChildEventListenerOrEventListenerObject
+      | ((this: HTMLElement, ev: OnChildEvent) => void),
   ): this {
-    // this type was some AI magic but if it works it works
     this.native.addEventListener(event, (e) => {
       const target = e.target as HTMLElement;
-      if (target !== null && target.matches(query)) {
+      if (target === null) return; //ignore event
+
+      let childTarget = target.closest(selector);
+      //bubble up until no match found or the parent element is reached
+      while (childTarget !== null && childTarget !== this.native) {
         if (typeof handler === "function") {
-          handler.call(target, e);
+          handler.call(
+            childTarget as HTMLElement,
+            Object.assign(e, { childTarget }),
+          );
         } else {
-          handler.handleEvent(e);
+          handler.handleEvent(Object.assign(e, { childTarget }));
         }
+
+        childTarget =
+          childTarget.parentElement !== null
+            ? childTarget.parentElement.closest(selector)
+            : null;
       }
     });
     return this;
@@ -680,21 +711,20 @@ export class ElementsWithUtils<
    */
   on<K extends keyof HTMLElementEventMap>(
     event: K,
-    handler: (this: T, ev: DomUtilsEvent<HTMLElementEventMap[K]>) => void,
+    handler: (this: T, ev: HTMLElementEventMap[K]) => void,
   ): this;
-  on(event: string, handler: DomUtilsEventListenerOrEventListenerObject): this;
+  on(event: string, handler: EventListenerOrEventListenerObject): this;
   on(
     event: keyof HTMLElementEventMap | string,
     handler:
-      | DomUtilsEventListenerOrEventListenerObject
-      | ((this: T, ev: DomUtilsEvent) => void),
+      | EventListenerOrEventListenerObject
+      | ((this: T, ev: Event) => void),
   ): this {
     for (const item of this) {
       item.on(event, handler);
     }
     return this;
   }
-
   /**
    * Set attribute value on all elements in the array
    */
diff --git a/frontend/vitest.config.ts b/frontend/vitest.config.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/vitest.config.ts b/vitest.config.ts

Original file line number	Diff line number	Diff line change
`@@ -6,5 +6,5 @@`
`6`	`6`	`"noEmit": true`
`7`	`7`	`},`
`8`	`8`	`"files": ["vitest.d.ts"],`
`9`		`- "include": ["./*/.spec.ts", "./setup-tests.ts"]`
	`9`	`+ "include": ["./*/.spec.ts", "./*/.jsdom-spec.ts", "./setup-tests.ts"]`
`10`	`10`	`}`