@ui5/webcomponents-tools 0.0.0-47cc17a26 → 0.0.0-49bade48d

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

@@ -17,6 +17,7 @@ import {
 	getTypeRefs,
 	normalizeDescription,
 	formatArrays,
+	formatSlotTypes,
 	isClass,
 	normalizeTagType,
 	logDocumentationError,
@@ -27,7 +28,44 @@ import { generateCustomData } from "cem-plugin-vs-code-custom-data-generator";
 import { customElementJetBrainsPlugin } from "custom-element-jet-brains-integration";
 
 const packageJSON = JSON.parse(fs.readFileSync("./package.json"));
+let aliasMap = {};
+
 const devMode = process.env.UI5_CEM_MODE === "dev";
+const isVerbose = process.env.UI5_VERBOSE === "true";
+
+/**
+ * Wraps a CEM plugin to suppress console output in quiet mode.
+ * @param {Object} plugin - The plugin to wrap
+ * @returns {Object} - Wrapped plugin with silent console during packageLinkPhase
+ */
+const wrapPluginForQuietMode = (plugin) => {
+	if (isVerbose) return plugin;
+
+	const originalPackageLinkPhase = plugin.packageLinkPhase;
+	if (!originalPackageLinkPhase) return plugin;
+
+	return {
+		...plugin,
+		packageLinkPhase(context) {
+			const originalLog = console.log;
+			console.log = () => { };
+			try {
+				return originalPackageLinkPhase.call(plugin, context);
+			} finally {
+				console.log = originalLog;
+			}
+		}
+	};
+};
+
+try {
+	aliasMap = JSON.parse(fs.readFileSync("./.ui5-cem-aliases.json"));
+} catch (e) {
+	if (devMode && isVerbose) {
+		console.warn("No .ui5-cem-aliases.json file found. Continuing without aliases.");
+	}
+}
+
 
 const extractClassNodeJSDoc = node => {
 	const fileContent = node.getFullText();
@@ -97,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;
@@ -158,6 +203,7 @@ function processClass(ts, classNode, moduleDoc) {
 
 			if (member.type?.text) {
 				member.type.text = formatArrays(member.type.text);
+				member.type.text = formatSlotTypes(member.type.text);
 			}
 
 			if (member.type && typeRefs.length) {
@@ -378,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;
 			}
 
@@ -486,6 +532,12 @@ export default {
 						}
 					}
 
+					moduleDoc.declarations.forEach(declaration => {
+						if (declaration.superclass?.name && aliasMap[declaration.superclass.name]) {
+							declaration.superclass.name = aliasMap[declaration.superclass.name];
+						}
+					})
+
 					const typeReferences = new Set();
 					const registerTypeReference = reference => typeReferences.add(JSON.stringify(reference))
 
@@ -524,7 +576,39 @@ export default {
 				}
 			}
 		},
-		generateCustomData({ outdir: "dist", cssFileName: null, cssPropertiesDocs: false }),
-		customElementJetBrainsPlugin({ outdir: "dist", cssFileName: null, cssPropertiesDocs: false })
+		{
+			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;
@@ -396,7 +400,12 @@ const displayDocumentationErrors = () => {
 }
 
 const formatArrays = (typeText) => {
-    return typeText?.replaceAll(/(\S+)\[\]/g, "Array<$1>")
+    return typeText?.replaceAll(/(\S+)\[\]/g, "Array<$1>");
+}
+
+// Convert Slot<T> and DefaultSlot<T> to Array<T> (the array is built into these types)
+const formatSlotTypes = (typeText) => {
+	return typeText?.replace(/(Default)?Slot<(.+?)>/g, 'Array<$2>');
 }
 
 export {
@@ -415,6 +424,7 @@ export {
     getTypeRefs,
     normalizeDescription,
     formatArrays,
+    formatSlotTypes,
     isClass,
     normalizeTagType,
     displayDocumentationErrors,