From 79cdfb48d258313138979a2e4ff33cacbeac6721 Mon Sep 17 00:00:00 2001
From: Pelle Wessman <pelle@kodfabrik.se>
Date: Fri, 12 Sep 2025 15:56:11 +0200
Subject: [PATCH] Tag name selector in `matches()` type narrows

---
 baselines/dom.generated.d.ts       |  3 +++
 baselines/ts5.5/dom.generated.d.ts |  3 +++
 baselines/ts5.6/dom.generated.d.ts |  3 +++
 src/build/emitter.ts               | 15 +++++++++++++++
 4 files changed, 24 insertions(+)

diff --git a/baselines/dom.generated.d.ts b/baselines/dom.generated.d.ts
index 604beb99a..797682aa7 100644
--- a/baselines/dom.generated.d.ts
+++ b/baselines/dom.generated.d.ts
@@ -11291,6 +11291,9 @@ interface Element extends Node, ARIAMixin, Animatable, ChildNode, NonDocumentTyp
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/matches)
      */
+    matches<K extends keyof HTMLElementTagNameMap>(selectors: K): this is HTMLElementTagNameMap[K];
+    matches<K extends keyof SVGElementTagNameMap>(selectors: K): this is SVGElementTagNameMap[K];
+    matches<K extends keyof MathMLElementTagNameMap>(selectors: K): this is MathMLElementTagNameMap[K];
     matches(selectors: string): boolean;
     /**
      * The **`releasePointerCapture()`** method of the Element interface releases (stops) _pointer capture_ that was previously set for a specific (PointerEvent) _pointer_.
diff --git a/baselines/ts5.5/dom.generated.d.ts b/baselines/ts5.5/dom.generated.d.ts
index d5ca4f096..b06711125 100644
--- a/baselines/ts5.5/dom.generated.d.ts
+++ b/baselines/ts5.5/dom.generated.d.ts
@@ -11281,6 +11281,9 @@ interface Element extends Node, ARIAMixin, Animatable, ChildNode, NonDocumentTyp
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/matches)
      */
+    matches<K extends keyof HTMLElementTagNameMap>(selectors: K): this is HTMLElementTagNameMap[K];
+    matches<K extends keyof SVGElementTagNameMap>(selectors: K): this is SVGElementTagNameMap[K];
+    matches<K extends keyof MathMLElementTagNameMap>(selectors: K): this is MathMLElementTagNameMap[K];
     matches(selectors: string): boolean;
     /**
      * The **`releasePointerCapture()`** method of the Element interface releases (stops) _pointer capture_ that was previously set for a specific (PointerEvent) _pointer_.
diff --git a/baselines/ts5.6/dom.generated.d.ts b/baselines/ts5.6/dom.generated.d.ts
index 23672a6c7..c438b0cb8 100644
--- a/baselines/ts5.6/dom.generated.d.ts
+++ b/baselines/ts5.6/dom.generated.d.ts
@@ -11291,6 +11291,9 @@ interface Element extends Node, ARIAMixin, Animatable, ChildNode, NonDocumentTyp
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/matches)
      */
+    matches<K extends keyof HTMLElementTagNameMap>(selectors: K): this is HTMLElementTagNameMap[K];
+    matches<K extends keyof SVGElementTagNameMap>(selectors: K): this is SVGElementTagNameMap[K];
+    matches<K extends keyof MathMLElementTagNameMap>(selectors: K): this is MathMLElementTagNameMap[K];
     matches(selectors: string): boolean;
     /**
      * The **`releasePointerCapture()`** method of the Element interface releases (stops) _pointer capture_ that was previously set for a specific (PointerEvent) _pointer_.
diff --git a/src/build/emitter.ts b/src/build/emitter.ts
index cd9f2cffe..1385cdb75 100644
--- a/src/build/emitter.ts
+++ b/src/build/emitter.ts
@@ -613,6 +613,19 @@ export function emitWebIdl(
     }
   }
 
+  /// Emit overloads for the matches method
+  function emitMatchesOverloads(m: Browser.Method) {
+    if (matchParamMethodSignature(m, "matches", "boolean", "string")) {
+      const paramName = m.signature[0].param![0].name;
+      for (const mapName of tagNameMapNames) {
+        printer.printLine(
+          `matches<K extends keyof ${mapName}>(${paramName}: K): this is ${mapName}[K];`,
+        );
+      }
+      printer.printLine(`matches(${paramName}: string): boolean;`);
+    }
+  }
+
   /// Emit overloads for the querySelector method
   function emitQuerySelectorOverloads(m: Browser.Method) {
     if (
@@ -988,6 +1001,8 @@ export function emitWebIdl(
         return emitCreateEventOverloads(m);
       case "getElementsByTagName":
         return emitGetElementsByTagNameOverloads(m);
+      case "matches":
+        return emitMatchesOverloads(m);
       case "querySelector":
         return emitQuerySelectorOverloads(m);
       case "querySelectorAll":