Make sure deprecated is always a string (#2271)

Bashamega · saschanaz · web-flow · commit 79b5a017e6ae · 2025-12-07T17:12:14.000Z
Co-authored-by: saschanaz &lt;saschanaz@users.noreply.github.com&gt;
diff --git a/baselines/dom.generated.d.ts b/baselines/dom.generated.d.ts
@@ -947,12 +947,12 @@ interface KeySystemTrackConfiguration {
 }
 
 interface KeyboardEventInit extends EventModifierInit {
-    /** @deprecated */
+    /** @deprecated `charCode` is inconsistent across environments, consider using `key` instead. */
     charCode?: number;
     code?: string;
     isComposing?: boolean;
     key?: string;
-    /** @deprecated */
+    /** @deprecated `keyCode` is inconsistent across environments, consider using `key` instead. */
     keyCode?: number;
     location?: number;
     repeat?: boolean;
@@ -9255,7 +9255,7 @@ interface CSSStyleProperties extends CSSStyleDeclarationBase {
      */
     wordSpacing: string;
     /**
-     * @deprecated
+     * @deprecated `word-wrap` is a legacy alias of `overflow-wrap`.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/overflow-wrap)
      */
@@ -39862,7 +39862,7 @@ interface WindowEventHandlers {
     /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
     onunhandledrejection: ((this: WindowEventHandlers, ev: PromiseRejectionEvent) => any) | null;
     /**
-     * @deprecated
+     * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
      */
@@ -42245,7 +42245,7 @@ declare var onstorage: ((this: Window, ev: StorageEvent) => any) | null;
 /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
 declare var onunhandledrejection: ((this: Window, ev: PromiseRejectionEvent) => any) | null;
 /**
- * @deprecated
+ * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
  *
  * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
  */
diff --git a/baselines/ts5.5/dom.generated.d.ts b/baselines/ts5.5/dom.generated.d.ts
@@ -944,12 +944,12 @@ interface KeySystemTrackConfiguration {
 }
 
 interface KeyboardEventInit extends EventModifierInit {
-    /** @deprecated */
+    /** @deprecated `charCode` is inconsistent across environments, consider using `key` instead. */
     charCode?: number;
     code?: string;
     isComposing?: boolean;
     key?: string;
-    /** @deprecated */
+    /** @deprecated `keyCode` is inconsistent across environments, consider using `key` instead. */
     keyCode?: number;
     location?: number;
     repeat?: boolean;
@@ -9245,7 +9245,7 @@ interface CSSStyleProperties extends CSSStyleDeclarationBase {
      */
     wordSpacing: string;
     /**
-     * @deprecated
+     * @deprecated `word-wrap` is a legacy alias of `overflow-wrap`.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/overflow-wrap)
      */
@@ -39836,7 +39836,7 @@ interface WindowEventHandlers {
     /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
     onunhandledrejection: ((this: WindowEventHandlers, ev: PromiseRejectionEvent) => any) | null;
     /**
-     * @deprecated
+     * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
      */
@@ -42219,7 +42219,7 @@ declare var onstorage: ((this: Window, ev: StorageEvent) => any) | null;
 /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
 declare var onunhandledrejection: ((this: Window, ev: PromiseRejectionEvent) => any) | null;
 /**
- * @deprecated
+ * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
  *
  * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
  */
diff --git a/baselines/ts5.6/dom.generated.d.ts b/baselines/ts5.6/dom.generated.d.ts
@@ -944,12 +944,12 @@ interface KeySystemTrackConfiguration {
 }
 
 interface KeyboardEventInit extends EventModifierInit {
-    /** @deprecated */
+    /** @deprecated `charCode` is inconsistent across environments, consider using `key` instead. */
     charCode?: number;
     code?: string;
     isComposing?: boolean;
     key?: string;
-    /** @deprecated */
+    /** @deprecated `keyCode` is inconsistent across environments, consider using `key` instead. */
     keyCode?: number;
     location?: number;
     repeat?: boolean;
@@ -9252,7 +9252,7 @@ interface CSSStyleProperties extends CSSStyleDeclarationBase {
      */
     wordSpacing: string;
     /**
-     * @deprecated
+     * @deprecated `word-wrap` is a legacy alias of `overflow-wrap`.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/overflow-wrap)
      */
@@ -39859,7 +39859,7 @@ interface WindowEventHandlers {
     /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
     onunhandledrejection: ((this: WindowEventHandlers, ev: PromiseRejectionEvent) => any) | null;
     /**
-     * @deprecated
+     * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
      */
@@ -42242,7 +42242,7 @@ declare var onstorage: ((this: Window, ev: StorageEvent) => any) | null;
 /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
 declare var onunhandledrejection: ((this: Window, ev: PromiseRejectionEvent) => any) | null;
 /**
- * @deprecated
+ * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
  *
  * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
  */
diff --git a/baselines/ts5.9/dom.generated.d.ts b/baselines/ts5.9/dom.generated.d.ts
@@ -944,12 +944,12 @@ interface KeySystemTrackConfiguration {
 }
 
 interface KeyboardEventInit extends EventModifierInit {
-    /** @deprecated */
+    /** @deprecated `charCode` is inconsistent across environments, consider using `key` instead. */
     charCode?: number;
     code?: string;
     isComposing?: boolean;
     key?: string;
-    /** @deprecated */
+    /** @deprecated `keyCode` is inconsistent across environments, consider using `key` instead. */
     keyCode?: number;
     location?: number;
     repeat?: boolean;
@@ -9252,7 +9252,7 @@ interface CSSStyleProperties extends CSSStyleDeclarationBase {
      */
     wordSpacing: string;
     /**
-     * @deprecated
+     * @deprecated `word-wrap` is a legacy alias of `overflow-wrap`.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/Reference/Properties/overflow-wrap)
      */
@@ -39859,7 +39859,7 @@ interface WindowEventHandlers {
     /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
     onunhandledrejection: ((this: WindowEventHandlers, ev: PromiseRejectionEvent) => any) | null;
     /**
-     * @deprecated
+     * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
      *
      * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
      */
@@ -42242,7 +42242,7 @@ declare var onstorage: ((this: Window, ev: StorageEvent) => any) | null;
 /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unhandledrejection_event) */
 declare var onunhandledrejection: ((this: Window, ev: PromiseRejectionEvent) => any) | null;
 /**
- * @deprecated
+ * @deprecated The unload event is not reliable, consider visibilitychange or pagehide events.
  *
  * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/unload_event)
  */
diff --git a/inputfiles/patches/cssom.kdl b/inputfiles/patches/cssom.kdl
@@ -7,9 +7,13 @@ interface CSSStyleDeclaration \
   forwardExtends=CSSStyleProperties
 
 interface CSSStyleProperties replaceReference=CSSStyleDeclaration {
-  property wordWrap deprecated=#true
-  
-  // The corresponding standardized property is not supported by
-  // anyone as of 2024-10.
-  property webkitLineClamp deprecated=#false
+  property wordWrap deprecated="`word-wrap` is a legacy alias of `overflow-wrap`."
+}
+
+removals {
+  interface CSSStyleProperties {
+    // The corresponding standardized property is not supported by
+    // anyone as of 2024-10.
+    property webkitLineClamp deprecated=""
+  }
 }
diff --git a/inputfiles/patches/html.kdl b/inputfiles/patches/html.kdl
@@ -12,9 +12,7 @@ interface HTMLDocument extends=Document exposed=Window
 interface-mixin MessageEventTarget overrideThis=T typeParameters=T
 
 interface-mixin WindowEventHandlers {
-  // TODO: pass a string instead for deprecated
-  // The unload event is not reliable, consider visibilitychange or pagehide events
-  property onunload deprecated=#true
+  property onunload deprecated="The unload event is not reliable, consider visibilitychange or pagehide events."
 }
 
 // Blink and Gecko support precommit but BCD is not updated yet
diff --git a/inputfiles/patches/uievents.kdl b/inputfiles/patches/uievents.kdl
@@ -1,7 +1,4 @@
 dictionary KeyboardEventInit {
-  // TODO: pass a string instead for deprecated
-  // charCode is inconsistent across environments, consider using .key instead
-  member charCode deprecated=#true
-  // keyCode is inconsistent across environments, consider using .key instead
-  member keyCode deprecated=#true
+  member charCode deprecated="`charCode` is inconsistent across environments, consider using `key` instead."
+  member keyCode deprecated="`keyCode` is inconsistent across environments, consider using `key` instead."
 }
diff --git a/src/build/patches.ts b/src/build/patches.ts
@@ -81,8 +81,8 @@ function handleTypeParameters(value: Value | Node) {
   };
 }
 
-function undefinedIfEmpty(object: object, output: object) {
-  return Object.entries(object).length ? output : undefined;
+function optionalNestedMember<T>(prop: string, object: object, output: T) {
+  return Object.entries(object).length ? { [prop]: output } : {};
 }
 
 /**
@@ -119,10 +119,12 @@ function convertKDLNodes(nodes: Node[]): DeepPartial<WebIdl> {
   }
 
   return {
-    enums: undefinedIfEmpty(enums, { enum: enums }),
-    mixins: undefinedIfEmpty(mixin, { mixin }),
-    interfaces: undefinedIfEmpty(interfaces, { interface: interfaces }),
-    dictionaries: undefinedIfEmpty(dictionary, { dictionary }),
+    ...optionalNestedMember("enums", enums, { enum: enums }),
+    ...optionalNestedMember("mixins", mixin, { mixin }),
+    ...optionalNestedMember("interfaces", interfaces, {
+      interface: interfaces,
+    }),
+    ...optionalNestedMember("dictionaries", dictionary, { dictionary }),
   };
 }
 
@@ -202,7 +204,7 @@ function handleMixinAndInterfaces(
   };
   return {
     name,
-    events: { event },
+    ...optionalNestedMember("events", event, { event }),
     properties: { property },
     methods: { method },
     ...optionalMember("extends", "string", node.properties?.extends),
@@ -256,7 +258,7 @@ function handleProperty(child: Node): Partial<Property> {
       ? handleTyped(typeNode)
       : optionalMember("type", "string", child.properties?.type)),
     ...optionalMember("readonly", "boolean", child.properties?.readonly),
-    ...optionalMember("deprecated", "boolean", child.properties?.deprecated),
+    ...optionalMember("deprecated", "string", child.properties?.deprecated),
   };
 }
 
@@ -379,7 +381,7 @@ function handleMember(c: Node): Partial<Member> {
     name,
     ...optionalMember("type", "string", c.properties?.type),
     ...optionalMember("required", "boolean", c.properties?.required),
-    ...optionalMember("deprecated", "boolean", c.properties?.deprecated),
+    ...optionalMember("deprecated", "string", c.properties?.deprecated),
     ...optionalMember("overrideType", "string", c.properties?.overrideType),
   };
 }
@@ -411,16 +413,18 @@ async function readPatchDocument(fileUrl: URL): Promise<Document> {
  */
 function convertForRemovals(obj: unknown): unknown {
   if (Array.isArray(obj)) {
-    const result = obj.map(convertForRemovals).filter((v) => v !== undefined);
-    return result.length === 0 ? null : result;
+    return obj.map(convertForRemovals).filter((v) => v !== undefined);
   }
   if (obj && typeof obj === "object") {
     const newObj: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(obj)) {
       if (key !== "name") {
         const cleaned = convertForRemovals(value);
-        if (cleaned !== undefined) {
+        // (intentionally covers null too)
+        if (typeof cleaned === "object") {
           newObj[key] = cleaned;
+        } else if (cleaned !== undefined) {
+          newObj[key] = null;
         }
       }
     }

Original file line number	Diff line number	Diff line change
`@@ -12,9 +12,7 @@ interface HTMLDocument extends=Document exposed=Window`
`12`	`12`	`interface-mixin MessageEventTarget overrideThis=T typeParameters=T`
`13`	`13`
`14`	`14`	`interface-mixin WindowEventHandlers {`
`15`		`- // TODO: pass a string instead for deprecated`
`16`		`- // The unload event is not reliable, consider visibilitychange or pagehide events`
`17`		`- property onunload deprecated=#true`
	`15`	`+ property onunload deprecated="The unload event is not reliable, consider visibilitychange or pagehide events."`
`18`	`16`	`}`
`19`	`17`
`20`	`18`	`// Blink and Gecko support precommit but BCD is not updated yet`