@ui5/webcomponents-tools 2.20.0-rc.2 → 2.20.0-rc.3

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.20.0-rc.3](https://github.com/UI5/webcomponents/compare/v2.20.0-rc.2...v2.20.0-rc.3) (2026-03-05)
+
+**Note:** Version bump only for package @ui5/webcomponents-tools
+
+
+
+
+
 # [2.20.0-rc.2](https://github.com/UI5/webcomponents/compare/v2.20.0-rc.1...v2.20.0-rc.2) (2026-02-26)
 
 

package/components-package/nps.js

@@ -68,7 +68,7 @@ const getScripts = (options) => {
 
 	const scripts = {
 		__ui5envs: {
-			UI5_CEM_MODE: options.dev,
+			UI5_CEM_MODE: typeof options.dev === "boolean" ? (options.dev ? "dev" : undefined) : options.dev,
 			UI5_TS: `${tsOption}`,
 			CSS_VARIABLES_TARGET: options.cssVariablesTarget ?? "root",
 			CYPRESS_COVERAGE: !!(options.internal?.cypress_code_coverage),
@@ -86,7 +86,7 @@ const getScripts = (options) => {
 			styleRelated: "ui5nps build.styles build.jsonImports build.jsImports",
 		},
 		prepare: {
-			default: `ui5nps clean prepare.all copy copyProps prepare.typescript generateAPI`,
+			default: `ui5nps clean prepare.all copy copyProps prepare.typescript`,
 			all: `ui5nps-p build.templates build.i18n prepare.styleRelated build.illustrations`, // concurently
 			styleRelated: "ui5nps build.styles build.jsonImports build.jsImports",
 			typescript: tsCommandOld,
@@ -165,9 +165,9 @@ const getScripts = (options) => {
 			bundle: `ui5nps-script ${LIB}dev-server/dev-server.mjs ${viteConfig}`,
 		},
 		generateAPI: {
-			default: tsOption ? "ui5nps generateAPI.generateCEM generateAPI.validateCEM" : "",
 			generateCEM: `ui5nps-script "${LIB}cem/cem.js" analyze --config "${LIB}cem/custom-elements-manifest.config.mjs"`,
 			validateCEM: `ui5nps-script "${LIB}cem/validate.js"`,
+			mergeCEM: `ui5nps-script "${LIB}cem/merge.mjs"`,
 		},
 	};
 

package/lib/cem/custom-elements-manifest.config.mjs

@@ -48,7 +48,7 @@ const wrapPluginForQuietMode = (plugin) => {
 		...plugin,
 		packageLinkPhase(context) {
 			const originalLog = console.log;
-			console.log = () => {};
+			console.log = () => { };
 			try {
 				return originalPackageLinkPhase.call(plugin, context);
 			} finally {
@@ -135,6 +135,13 @@ function processClass(ts, classNode, moduleDoc) {
 		if (currClass.superclass?.name === "UI5Element") {
 			currClass.customElement = true;
 		}
+	} else if (currClass.customElement && classNode?.heritageClauses) {
+		// Find the extends clause (not implements)
+		const extendsClause = classNode.heritageClauses.find(clause => clause.token === ts.SyntaxKind.ExtendsKeyword);
+		if (extendsClause?.types?.[0]?.expression?.text) {
+			const extendedClass = extendsClause.types[0].expression.text;
+			logDocumentationError(moduleDoc.path, `Class extends ${extendedClass} but @extends tag is missing in JSDoc`);
+		}
 	}
 
 	if (!currClass._ui5implements.length) delete currClass._ui5implements;
@@ -417,10 +424,10 @@ const processPublicAPI = object => {
 		return true;
 	}
 	for (const key of keys) {
-		if ((key === "privacy" && object[key] !== "public") || (key === "_ui5privacy" && object[key] !== "public")) {
+		if (((key === "privacy" && object[key] !== "public") || (key === "_ui5privacy" && object[key] !== "public")) && !object.customElement) {
 			return true;
 		} else if (typeof object[key] === "object") {
-			if (key === "cssParts" || key === "attributes" || key === "_ui5implements") {
+			if (key === "cssParts" || key === "cssStates" || key === "attributes" || key === "_ui5implements") {
 				continue;
 			}
 
@@ -569,6 +576,38 @@ export default {
 				}
 			}
 		},
+		{
+			name: 'alphabetical-sort-plugin',
+			packageLinkPhase({ customElementsManifest }) {
+				const sortByName = (arr) => {
+					if (Array.isArray(arr)) {
+						arr.sort((a, b) => {
+							if (a?.name && b?.name) {
+								return a.name.localeCompare(b.name);
+							}
+							return 0;
+						});
+					}
+				};
+
+				const sortArraysInObject = (obj) => {
+					if (!obj || typeof obj !== 'object') return;
+
+					for (const key in obj) {
+						if (Array.isArray(obj[key])) {
+							sortByName(obj[key]);
+							obj[key].forEach(item => sortArraysInObject(item));
+						} else if (typeof obj[key] === 'object') {
+							sortArraysInObject(obj[key]);
+						}
+					}
+				};
+
+				customElementsManifest.modules?.forEach(moduleDoc => {
+					sortArraysInObject(moduleDoc);
+				});
+			}
+		},
 		wrapPluginForQuietMode(generateCustomData({ outdir: "dist", cssFileName: null, cssPropertiesDocs: false })),
 		wrapPluginForQuietMode(customElementJetBrainsPlugin({ outdir: "dist", cssFileName: null, cssPropertiesDocs: false }))
 	],

package/lib/cem/merge.mjs

@@ -0,0 +1,220 @@
+import { pathToFileURL } from "url";
+import path from "path";
+import { createRequire } from 'module';
+import { readFile, writeFile } from "fs/promises";
+
+const require = createRequire(import.meta.url);
+
+const UI5_BASE_CLASS = "UI5Element";
+
+const main = async (argv) => {
+    let customElementsPath = null;
+    const CACHED_CEMS = new Map();
+    const DECLARATION_PACKAGE = new WeakMap();
+    const DECLARATION_MODULE = new WeakMap();
+
+    function removeInheritedFrom(obj) {
+        if (obj === null || typeof obj !== 'object') {
+            return obj;
+        }
+
+        if (Array.isArray(obj)) {
+            return obj.map(item => removeInheritedFrom(item));
+        }
+
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === 'inheritedFrom') {
+                continue;
+            }
+            result[key] = removeInheritedFrom(value);
+        }
+        return result;
+    }
+
+    async function readPackageJson(filePath) {
+        try {
+            return JSON.parse(await readFile(filePath, "utf-8"));
+        } catch (error) {
+            throw new Error(`Failed to read package.json at ${filePath}: ${error.message}`);
+        }
+    }
+
+    async function loadPackageJson(depName) {
+        try {
+            // First try the standard require method (works when exports includes package.json)
+            const pkg = require(`${depName}/package.json`);
+            const pkgPath = require.resolve(`${depName}/package.json`);
+            return { path: path.dirname(pkgPath), pkg };
+        } catch (e) {
+            // If that fails, resolve the package path and read package.json directly
+            try {
+                const packagePath = require.resolve(depName);
+                let currentDir = path.dirname(packagePath);
+
+                // Navigate up to find package.json (the resolved path might be deep in dist/ or similar)
+                while (currentDir !== path.parse(currentDir).root) {
+                    try {
+                        const pkgPath = path.join(currentDir, 'package.json');
+                        const content = await readFile(pkgPath, 'utf-8');
+                        const pkg = JSON.parse(content);
+
+                        // Verify this is the correct package.json by checking the name
+                        if (pkg.name === depName) {
+                            return { path: currentDir, pkg };
+                        }
+                    } catch {
+                        // Continue searching up the directory tree
+                    }
+                    currentDir = path.dirname(currentDir);
+                }
+            } catch (resolveError) {
+                // console.warn(`Could not resolve ${depName}:`, resolveError.message);
+            }
+            return null;
+        }
+    }
+
+    async function collectThirdPartyCem() {
+        const packageJSONPath = path.resolve(process.cwd(), "package.json");
+        const packageJSON = await readPackageJson(packageJSONPath);
+
+        const dependencyKeys = Object.keys(packageJSON).filter(key => key.toLowerCase().includes("dependencies"));
+        const dependencies = dependencyKeys.flatMap(key => Object.keys(packageJSON[key]));
+
+        const thirdPartCEM = (await Promise.all(dependencies.map(async dep => {
+            const result = await loadPackageJson(dep);
+            if (!result?.pkg?.customElements) return null;
+
+            return {
+                path: result.path,
+                name: dep,
+                cem: result.pkg.customElements
+            };
+        }))).filter(Boolean);
+
+        await Promise.all(thirdPartCEM.map(async dep => {
+            const cemPath = path.resolve(dep.path, dep.cem);
+            try {
+                const cemContent = JSON.parse(await readFile(cemPath, "utf-8"));
+                CACHED_CEMS.set(dep.name, cemContent);
+            } catch (error) {
+                console.warn(`Failed to read CEM for ${dep.name} from ${cemPath}: ${error.message}`);
+            }
+        }));
+    }
+
+    async function readCurrentCEM() {
+        const packageJSONPath = path.resolve(process.cwd(), "package.json");
+        const packageJSON = await readPackageJson(packageJSONPath);
+
+        if (!packageJSON?.customElements) {
+            return null;
+        }
+
+        customElementsPath = packageJSON.customElements;
+        const cemPath = path.resolve(process.cwd(), customElementsPath);
+
+        try {
+            const cemContent = JSON.parse(await readFile(cemPath, "utf-8"));
+            CACHED_CEMS.set(packageJSON.name, cemContent);
+            return cemContent;
+        } catch (error) {
+            throw new Error(`Failed to read CEM from ${cemPath}: ${error.message}`);
+        }
+    }
+
+    async function resolveReference(ref) {
+        const pkg = CACHED_CEMS.get(ref.package);
+
+        if (!pkg) {
+            return null;
+        }
+
+        const mod = (pkg.modules || []).find(m => m.path === ref.module);
+
+        if (!mod) {
+            return null;
+        }
+
+        const declaration = (mod.declarations || []).find(d => d.name === ref.name);
+
+        if (!declaration) {
+            return null;
+        }
+
+        DECLARATION_PACKAGE.set(declaration, ref.package);
+        DECLARATION_MODULE.set(declaration, ref.module);
+
+        return resolveDeclaration(declaration);
+    }
+
+    async function resolveDeclaration(declaration) {
+        if (!declaration.superclass || declaration.superclass.name === UI5_BASE_CLASS) {
+            return [declaration];
+        }
+
+        const superclassDeclarations = await resolveReference(declaration.superclass);
+        return [declaration, superclassDeclarations].flat().filter(Boolean);
+    }
+
+    const merge = async () => {
+        const currentCEM = await readCurrentCEM();
+        if (!currentCEM) {
+            throw new Error("No custom elements manifest found in current project");
+        }
+
+        await collectThirdPartyCem();
+
+        const modules = currentCEM.modules || [];
+
+        for (const mod of modules) {
+            const declarations = (mod.declarations || []).filter(d => d.kind === "class");
+
+            for (const declaration of declarations) {
+                const declarationHierarchy = await resolveDeclaration(declaration);
+                const allKeys = declarationHierarchy.flatMap(dec => Object.keys(dec));
+                const uniqueKeys = [...new Set(allKeys)];
+                const arrayKeys = uniqueKeys
+                    .filter(key => !key.startsWith("_ui5"))
+                    .filter(key => declarationHierarchy.some(dec => Array.isArray(dec[key])));
+
+                for (const key of arrayKeys) {
+                    const allItems = declarationHierarchy.flatMap(dec => dec[key] || []);
+
+                    // Remove duplicates based on name property
+                    const seen = new Set();
+                    declaration[key] = allItems.filter(item => {
+                        if (!item.name) return true;
+                        if (seen.has(item.name)) return false;
+                        seen.add(item.name);
+                        return true;
+                    });
+                }
+            }
+        }
+
+        const cleanedCEM = removeInheritedFrom(currentCEM);
+        const outputPath = path.resolve(process.cwd(), customElementsPath);
+
+        try {
+            await writeFile(outputPath, JSON.stringify(cleanedCEM, null, 2), "utf-8");
+            console.log(`Successfully merged CEM to ${outputPath}`);
+        } catch (error) {
+            throw new Error(`Failed to write merged CEM to ${outputPath}: ${error.message}`);
+        }
+    };
+
+    await merge();
+}
+
+const filePath = process.argv[1];
+const fileUrl = pathToFileURL(filePath).href;
+
+if (import.meta.url === fileUrl) {
+    main(process.argv)
+}
+
+export default {
+    _ui5mainFn: main
+}

package/lib/cem/schema-internal.json

@@ -1,6 +1,34 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "CssCustomState": {
+      "description": "The description of a CSS Custom State\nhttps://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet",
+      "properties": {
+        "deprecated": {
+          "description": "Whether the CSS custom state is deprecated.\nIf the value is a string, it's the reason for the deprecation.",
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
+        "description": {
+          "description": "A markdown description.",
+          "type": "string"
+        },
+        "name": {
+          "description": "The name of the state. Note: Unlike CSS custom properties, custom states\ndo not have a leading `--`.",
+          "type": "string"
+        },
+        "summary": {
+          "description": "A markdown summary suitable for display in a listing.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
     "Attribute": {
       "additionalProperties": false,
       "properties": {
@@ -521,6 +549,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -676,6 +710,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -1039,7 +1079,7 @@
           "type": "string"
         },
         "path": {
-          "description": "Path to the javascript file needed to be imported. \n(not the path for example to a typescript file.)",
+          "description": "Path to the javascript file needed to be imported.\n(not the path for example to a typescript file.)",
           "type": "string"
         },
         "summary": {

package/lib/cem/schema.json

@@ -258,6 +258,34 @@
       ],
       "type": "object"
     },
+    "CssCustomState": {
+      "description": "The description of a CSS Custom State\nhttps://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet",
+      "properties": {
+        "deprecated": {
+          "description": "Whether the CSS custom state is deprecated.\nIf the value is a string, it's the reason for the deprecation.",
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
+        "description": {
+          "description": "A markdown description.",
+          "type": "string"
+        },
+        "name": {
+          "description": "The name of the state. Note: Unlike CSS custom properties, custom states\ndo not have a leading `--`.",
+          "type": "string"
+        },
+        "summary": {
+          "description": "A markdown summary suitable for display in a listing.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    },
     "CssPart": {
       "description": "The description of a CSS Part",
       "properties": {
@@ -307,6 +335,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -451,6 +485,12 @@
           },
           "type": "array"
         },
+        "cssStates": {
+          "items": {
+            "$ref": "#/definitions/CssCustomState"
+          },
+          "type": "array"
+        },
         "customElement": {
           "description": "Distinguishes a regular JavaScript class from a\ncustom element class",
           "enum": [
@@ -765,7 +805,7 @@
           "type": "string"
         },
         "path": {
-          "description": "Path to the javascript file needed to be imported. \n(not the path for example to a typescript file.)",
+          "description": "Path to the javascript file needed to be imported.\n(not the path for example to a typescript file.)",
           "type": "string"
         },
         "summary": {

package/lib/cem/types-internal.d.ts

@@ -56,7 +56,7 @@ export interface JavaScriptModule {
   kind: 'javascript-module';
 
   /**
-   * Path to the javascript file needed to be imported. 
+   * Path to the javascript file needed to be imported.
    * (not the path for example to a typescript file.)
    */
   path: string;
@@ -258,6 +258,8 @@ export interface CustomElement extends ClassLike {
 
   cssProperties?: CssCustomProperty[];
 
+  cssStates?: CssCustomState[];
+
   demos?: Demo[];
 
   /**
@@ -416,6 +418,34 @@ export interface CssPart {
   deprecated?: boolean | string;
 }
 
+/**
+ * The description of a CSS Custom State
+ * https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+ */
+export interface CssCustomState {
+  /**
+   * The name of the state. Note: Unlike CSS custom properties, custom states
+   * do not have a leading `--`.
+   */
+  name: string;
+
+  /**
+   * A markdown summary suitable for display in a listing.
+   */
+  summary?: string;
+
+  /**
+   * A markdown description.
+   */
+  description?: string;
+
+  /**
+   * Whether the CSS custom state is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
+   */
+  deprecated?: boolean | string;
+}
+
 export interface CssCustomProperty {
   /**
    * The name of the property, including leading `--`.
@@ -632,7 +662,7 @@ export interface ClassField extends PropertyLike {
 export interface CustomElementField extends ClassField {
   /**
    * The corresponding attribute name if there is one.
-   * 
+   *
    * If this property is defined, the attribute must be listed in the classes'
    * `attributes` array.
    */

package/lib/cem/types.d.ts

@@ -56,7 +56,7 @@ export interface JavaScriptModule {
   kind: 'javascript-module';
 
   /**
-   * Path to the javascript file needed to be imported. 
+   * Path to the javascript file needed to be imported.
    * (not the path for example to a typescript file.)
    */
   path: string;
@@ -250,6 +250,8 @@ export interface CustomElement extends ClassLike {
 
   cssProperties?: CssCustomProperty[];
 
+  cssStates?: CssCustomState[];
+
   demos?: Demo[];
 
   /**
@@ -372,6 +374,34 @@ export interface CssPart {
   deprecated?: boolean | string;
 }
 
+/**
+ * The description of a CSS Custom State
+ * https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+ */
+export interface CssCustomState {
+  /**
+   * The name of the state. Note: Unlike CSS custom properties, custom states
+   * do not have a leading `--`.
+   */
+  name: string;
+
+  /**
+   * A markdown summary suitable for display in a listing.
+   */
+  summary?: string;
+
+  /**
+   * A markdown description.
+   */
+  description?: string;
+
+  /**
+   * Whether the CSS custom state is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
+   */
+  deprecated?: boolean | string;
+}
+
 export interface CssCustomProperty {
   /**
    * The name of the property, including leading `--`.
@@ -573,7 +603,7 @@ export interface ClassField extends PropertyLike {
 export interface CustomElementField extends ClassField {
   /**
    * The corresponding attribute name if there is one.
-   * 
+   *
    * If this property is defined, the attribute must be listed in the classes'
    * `attributes` array.
    */

package/lib/cem/utils.mjs

@@ -240,7 +240,7 @@ const allowedTags = {
     event: [...commonTags, "param", "native", "allowPreventDefault"],
     eventParam: [...commonTags],
     method: [...commonTags, "param", "returns", "override"],
-    class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart"],
+    class: [...commonTags, "constructor", "class", "abstract", "experimental", "implements", "extends", "slot", "csspart", "cssstate", "cssState"],
     enum: [...commonTags, "experimental",],
     enumMember: [...commonTags, "experimental",],
     interface: [...commonTags, "experimental",],
@@ -330,6 +330,9 @@ const validateJSDocTag = (tag) => {
             return tag.type && tag.name && tag.description;
         case "csspart":
             return !tag.type && tag.name && tag.description;
+        case "cssState":
+        case "cssstate":
+            return !tag.type && tag.name && tag.description;
         case "since":
             return !tag.type && tag.name;
         case "returns":
@@ -360,7 +363,8 @@ const validateJSDocComment = (fieldType, jsdocComment, node, moduleDoc) => {
         }
 
         if (!isValid) {
-            logDocumentationError(moduleDoc.path, `Incorrect use of @${tag.tag}. Ensure it is part of ${fieldType} JSDoc tags.`)
+            const nodeName = node ? ` in '${node}'` : '';
+            logDocumentationError(moduleDoc.path, `Incorrect use of @${tag.tag}${nodeName}. Ensure it is part of ${fieldType} JSDoc tags.`)
         }
 
         return !!isValid;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ui5/webcomponents-tools",
-  "version": "2.20.0-rc.2",
+  "version": "2.20.0-rc.3",
   "description": "UI5 Web Components: webcomponents.tools",
   "author": "SAP SE (https://www.sap.com)",
   "license": "Apache-2.0",
@@ -82,5 +82,5 @@
     "esbuild": "^0.25.0",
     "yargs": "^17.5.1"
   },
-  "gitHead": "98b851b62424d1b81b69d58768924dc4a7a17096"
+  "gitHead": "d1767f2375f2b81e1187f9c58bb3b0eaf28b139e"
 }