Feature: Add method handling to mixin processing in KDL (#2100)

Co-authored-by: Kagami Sascha Rosylight <[email protected]>

Author: Bashamega

inputfiles/addedTypes.jsonc

@@ -1,28 +1,4 @@
 {
-    "mixins": {
-        "mixin": {
-            "DocumentOrShadowRoot": {
-                // Manually moved from Document
-                // See https://github.com/w3c/csswg-drafts/issues/5886 and https://github.com/w3c/csswg-drafts/issues/556
-                "methods": {
-                    "method": {
-                        "elementFromPoint": {
-                            "name": "elementFromPoint",
-                            "overrideSignatures": [
-                                "elementFromPoint(x: number, y: number): Element | null"
-                            ]
-                        },
-                        "elementsFromPoint": {
-                            "name": "elementsFromPoint",
-                            "overrideSignatures": [
-                                "elementsFromPoint(x: number, y: number): Element[]"
-                            ]
-                        }
-                    }
-                }
-            }
-        }
-    },
     "interfaces": {
         "interface": {
             // ImportMeta is not a true DOM interface, but we are forced to declare it as one in order to emit method definitions.

inputfiles/patches/cssom-view.kdl

@@ -0,0 +1,16 @@
+// Manually moved from Document
+// See https://github.com/w3c/csswg-drafts/issues/5886 and https://github.com/w3c/csswg-drafts/issues/556
+interface-mixin DocumentOrShadowRoot {
+  method elementFromPoint {
+    type Element nullable=#true
+    param x type=long
+    param y type=long
+  }
+  method elementsFromPoint {
+    type sequence {
+      type Element
+    }
+    param x type=long
+    param y type=long
+  }
+}

src/build/patches.ts

@@ -1,5 +1,13 @@
 import { parse, type Value, type Node } from "kdljs";
-import type { Enum, Event, Property, Interface, WebIdl } from "./types.js";
+import type {
+  Enum,
+  Event,
+  Property,
+  Interface,
+  WebIdl,
+  Method,
+  Typed,
+} from "./types.js";
 import { readdir, readFile } from "fs/promises";
 import { merge } from "./helpers.js";
 
@@ -25,6 +33,28 @@ function optionalMember<const T>(prop: string, type: T, value?: Value) {
   };
 }
 
+function string(arg: unknown): string {
+  if (typeof arg !== "string") {
+    throw new Error(`Expected a string but found ${typeof arg}`);
+  }
+  return arg;
+}
+
+function handleTyped(type: Node): Typed {
+  const isTyped = type.name == "type";
+  if (!isTyped) {
+    throw new Error("Expected a type node");
+  }
+  const name = string(type.values[0]);
+  const subType =
+    type.children.length > 0 ? handleTyped(type.children[0]) : undefined;
+  return {
+    type: name,
+    subtype: subType,
+    ...optionalMember("nullable", "boolean", type.properties?.nullable),
+  };
+}
+
 /**
  * Converts patch files in KDL to match the [types](types.d.ts).
  */
@@ -40,10 +70,7 @@ function parseKDL(kdlText: string): DeepPartial<WebIdl> {
   const mixin: Record<string, DeepPartial<Interface>> = {};
 
   for (const node of nodes) {
-    const name = node.values[0];
-    if (typeof name !== "string") {
-      throw new Error(`Missing name for ${node.name}`);
-    }
+    const name = string(node.values[0]);
     switch (node.name) {
       case "enum":
         enums[name] = handleEnum(node);
@@ -66,10 +93,7 @@ function parseKDL(kdlText: string): DeepPartial<WebIdl> {
  * @param enums The record of enums to update.
  */
 function handleEnum(node: Node): Enum {
-  const name = node.properties?.name || node.values[0];
-  if (typeof name !== "string") {
-    throw new Error("Missing enum name");
-  }
+  const name = string(node.properties?.name || node.values[0]);
   const values: string[] = [];
 
   for (const child of node.children) {
@@ -96,23 +120,26 @@ function handleEnum(node: Node): Enum {
  */
 function handleMixin(node: Node): DeepPartial<Interface> {
   const name = node.values[0];
-  if (typeof name !== "string") {
-    throw new Error("Missing mixin name");
-  }
 
   const event: Event[] = [];
   const property: Record<string, Partial<Property>> = {};
+  const method: Record<string, Partial<Method>> = {};
 
   for (const child of node.children) {
     switch (child.name) {
       case "event":
         event.push(handleEvent(child));
         break;
       case "property": {
-        const propName = child.values[0] as string;
+        const propName = string(child.values[0]);
         property[propName] = handleProperty(child);
         break;
       }
+      case "method": {
+        const methodName = string(child.values[0]);
+        method[methodName] = handleMethod(child);
+        break;
+      }
       default:
         throw new Error(`Unknown node name: ${child.name}`);
     }
@@ -122,6 +149,7 @@ function handleMixin(node: Node): DeepPartial<Interface> {
     name,
     events: { event },
     properties: { property },
+    methods: { method },
     ...optionalMember("extends", "string", node.properties?.extends),
   } as DeepPartial<Interface>;
 }
@@ -132,8 +160,8 @@ function handleMixin(node: Node): DeepPartial<Interface> {
  */
 function handleEvent(child: Node): Event {
   return {
-    name: child.values[0] as string,
-    type: child.properties.type as string,
+    name: string(child.values[0]),
+    type: string(child.properties.type),
   };
 }
 
@@ -143,13 +171,57 @@ function handleEvent(child: Node): Event {
  */
 function handleProperty(child: Node): Partial<Property> {
   return {
-    name: child.values[0] as string,
+    name: string(child.values[0]),
     ...optionalMember("exposed", "string", child.properties?.exposed),
     ...optionalMember("optional", "boolean", child.properties?.optional),
     ...optionalMember("overrideType", "string", child.properties?.overrideType),
   };
 }
 
+/**
+ * Handles a child node of type "method" and adds it to the method object.
+ * @param child The child node to handle.
+ */
+function handleMethod(child: Node): Partial<Method> {
+  const name = string(child.values[0]);
+
+  let typeNode: Node | undefined;
+  const params: { name: string; type: string }[] = [];
+
+  for (const c of child.children) {
+    switch (c.name) {
+      case "type":
+        if (typeNode) {
+          throw new Error(`Method "${name}" has multiple type nodes (invalid)`);
+        }
+        typeNode = c;
+        break;
+
+      case "param":
+        params.push({
+          name: string(c.values[0]),
+          type: string(c.properties.type),
+        });
+        break;
+
+      default:
+        throw new Error(`Unexpected child "${c.name}" in method "${name}"`);
+    }
+  }
+
+  if (!typeNode) {
+    throw new Error(`Method "${name}" is missing a return type`);
+  }
+
+  const signature: Method["signature"] = [
+    {
+      param: params,
+      ...handleTyped(typeNode),
+    },
+  ];
+  return { name, signature };
+}
+
 /**
  * Collect all file URLs in a directory.
  */