@ui5/builder 4.1.4 → 4.1.6

package/CHANGELOG.md

@@ -2,7 +2,18 @@
 All notable changes to this project will be documented in this file.  
 This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-A list of unreleased changes can be found [here](https://github.com/SAP/ui5-builder/compare/v4.1.4...HEAD).
+A list of unreleased changes can be found [here](https://github.com/SAP/ui5-builder/compare/v4.1.6...HEAD).
+
+<a name="v4.1.6"></a>
+## [v4.1.6] - 2026-04-08
+### Bug Fixes
+- **Bundler:** Also detect import.meta as ESM indicator [`58013d5`](https://github.com/SAP/ui5-builder/commit/58013d5a75e3fbf245b0042fb0b81f4e729a7a55)
+- **Bundler:** Skip ESM modules during bundling and log errors [`d28f63a`](https://github.com/SAP/ui5-builder/commit/d28f63a6ace823d9fcfac23312c09e66be6fb7d4)
+- **Bundler:** Reduce noise from ESM parse errors [`bd574bb`](https://github.com/SAP/ui5-builder/commit/bd574bb231cc4e5f1af0b12c12c3365dee5eb80d)
+
+
+<a name="v4.1.5"></a>
+## [v4.1.5] - 2026-03-25
 
 <a name="v4.1.4"></a>
 ## [v4.1.4] - 2026-02-16
@@ -1016,6 +1027,8 @@ to load the custom bundle file instead.
 
 ### Features
 - Add ability to configure component preloads and custom bundles [`2241e5f`](https://github.com/SAP/ui5-builder/commit/2241e5ff98fd95f1f80cc74959655ae7a9c660e7)
+[v4.1.6]: https://github.com/SAP/ui5-builder/compare/v4.1.5...v4.1.6
+[v4.1.5]: https://github.com/SAP/ui5-builder/compare/v4.1.4...v4.1.5
 [v4.1.4]: https://github.com/SAP/ui5-builder/compare/v4.1.3...v4.1.4
 [v4.1.3]: https://github.com/SAP/ui5-builder/compare/v4.1.2...v4.1.3
 [v4.1.2]: https://github.com/SAP/ui5-builder/compare/v4.1.1...v4.1.2

package/lib/lbt/bundle/Builder.js

@@ -597,10 +597,11 @@ class BundleBuilder {
 		}
 	}
 
-	writeRequires(section) {
+	async writeRequires(section) {
 		if (section.modules.length === 0) {
 			return;
 		}
+
 		this.outW.ensureNewLine();
 		if (section.async === false) {
 			section.modules.forEach( (module) => {
@@ -767,7 +768,7 @@ async function rewriteDefine({moduleName, moduleContent, moduleSourceMap}) {
 	} catch (e) {
 		log.error(`Error while parsing ${moduleName}: ${e.message}`);
 		log.verbose(e.stack);
-		return {};
+		return null;
 	}
 
 	if ( ast.type === Syntax.Program &&

package/lib/lbt/bundle/ResolvedBundleDefinition.js

@@ -67,6 +67,7 @@ class ResolvedBundleDefinition {
 						return pool.getModuleInfo(submodule).then(
 							(subinfo) => {
 								if (!bundleInfo.subModules.includes(subinfo.name) &&
+									subinfo.format !== ModuleInfo.Format.ESM &&
 									(!subinfo.requiresTopLevelScope ||
 										(subinfo.requiresTopLevelScope && allowStringBundling))) {
 									bundleInfo.addSubModule(subinfo);

package/lib/lbt/bundle/Resolver.js

@@ -4,6 +4,7 @@
 
 import topologicalSort from "../graph/topologicalSort.js";
 import {getRendererName} from "../UI5ClientConstants.js";
+import ModuleInfo from "../resources/ModuleInfo.js";
 import ResourceFilterList from "../resources/ResourceFilterList.js";
 import {SectionType} from "./BundleDefinition.js";
 import ResolvedBundleDefinition from "./ResolvedBundleDefinition.js";
@@ -135,6 +136,16 @@ class BundleResolver {
 							const dependencyInfo = resource && resource.info;
 							let promises = [];
 
+							// Skip ESM modules — they can't be bundled
+							if (resource?.info?.format === ModuleInfo.Format.ESM) {
+								log.error(
+									`Module ${resourceName} is an ECMAScript Module (ESM), ` +
+									`which is not supported for bundling. ` +
+									`The module will be skipped.`
+								);
+								return;
+							}
+
 							if ( isBundle && !decomposable ) {
 								resource.info.subModules.forEach(
 									(included) => {

package/lib/lbt/resources/ModuleInfo.js

@@ -25,7 +25,8 @@ const CONDITIONAL = 2;
 const Format = {
 	UI5_LEGACY: "ui5-declare",
 	UI5_DEFINE: "ui5-define",
-	AMD: "amd"
+	AMD: "amd",
+	ESM: "esm"
 };
 
 /**

package/lib/lbt/resources/ResourcePool.js

@@ -62,8 +62,12 @@ async function determineDependencyInfo(resource, rawInfo, pool) {
 		try {
 			ast = parseJS(code, {comment: true});
 		} catch (err) {
-			log.error(`Failed to parse ${resource.name}: ${err.message}`);
+			log.verbose(`Failed to parse ${resource.name}: ${err.message}`);
 			log.verbose(err.stack);
+			if (err.message.includes("'import' and 'export' may appear only with 'sourceType: module'") ||
+				err.message.includes("Cannot use 'import.meta' outside a module")) {
+				info.format = ModuleInfo.Format.ESM;
+			}
 		}
 		if (ast) {
 			try {
@@ -243,4 +247,3 @@ class ResourcePool {
 }
 
 export default ResourcePool;
-

package/lib/processors/jsdoc/lib/transformApiJson.js

@@ -47,10 +47,10 @@ const typeParser = new TypeParser();
  * @param {string} sLibraryFile Path to the .library file of the library, used to extract further documentation information
  * @param {string|string[]} vDependencyAPIFiles Path of folder that contains api.json files of predecessor libs or
  *                 an array of paths of those files
- * @param {string} sFAQDir Path to the directory containing the sources for the FAQ section in APiRef
+ * @param {string} sSectionsDir Path to the directory containing the sources for the sections (FAQ, documentation, etc.) in the API Reference
  * @returns {Promise} A Promise that resolves after the transformation has been completed
  */
-function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, sFAQDir, options) {
+function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles, sSectionsDir, options) {
 	const fs = options && options.fs || require("fs");
 	const returnOutputFiles = options && !!options.returnOutputFiles;
 
@@ -59,7 +59,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	log.info("  output file: " + sOutputFile);
 	log.info("  library file: " + sLibraryFile);
 	log.info("  dependency dir: " + vDependencyAPIFiles);
-	log.info("  FAQ src dir: " + sFAQDir);
+	log.info("  sections src dir: " + sSectionsDir);
 	if (options && options.fs) {
 		log.info("Using custom fs.");
 	}
@@ -156,9 +156,10 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	 *      UI5Types: ["sap.ui.core.Control"] // skip template if its value is "${0}" (default value)
 	 *    }
 	 * @param {string} sComplexType
+	 * @param {Object<string,object>} oAllDependentAPIs Map of entity names to their symbol
 	 * @returns {{template=: string, UI5Types=: string[]}}
 	 */
-	function parseUI5Types(sComplexType) {
+	function parseUI5Types(sComplexType, oAllDependentAPIs) {
 		let oParsed;
 		try {
 			oParsed = typeParser.parseSimpleTypes(sComplexType, isUI5Type);
@@ -176,6 +177,14 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 		if (oParsed.simpleTypes?.length) { // it can be empty if none of the included simple types satisfied the filter function
 			result.UI5Types = oParsed.simpleTypes;
+
+			// check whether the type refers to a typedef and set a marker
+			if (result.template == null && result.UI5Types.length === 1) {
+				const symbol = oAllDependentAPIs[result.UI5Types[0]];
+				if (symbol?.kind === "typedef" && Array.isArray(symbol.properties)) {
+					result.refersToTypedef = true;
+				}
+			}
 		}
 
 		return result;
@@ -266,6 +275,8 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	 * @param {object} oChainObject chain object
 	 */
 	const transformApiJson = function (oChainObject) {
+		const {oAllDependentAPIs} = oChainObject;
+
 		// Function is a copy from: LibraryInfo.js => LibraryInfo.prototype._getActualComponent => "match" inline method
 		function matchComponent(sModuleName, sPattern) {
 			sModuleName = sModuleName.toLowerCase();
@@ -435,7 +446,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 						// Types
 						oParameter.types = [];
 						if (oParameter.type) {
-							oParameter.typeInfo = parseUI5Types(oParameter.type);
+							oParameter.typeInfo = parseUI5Types(oParameter.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oParameter.type;
 						}
@@ -520,7 +531,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 					// Type
 					if (oSymbol.kind !== "enum") { // enum properties don't have an own type
 						if (oProperty.type) {
-							oProperty.typeInfo = parseUI5Types(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -560,7 +571,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Type
 						if (oProperty.type) {
-							oProperty.typeInfo = parseUI5Types(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -687,7 +698,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Link Enabled
 						if (oSetting.type) {
-							oSetting.typeInfo = parseUI5Types(oSetting.type);
+							oSetting.typeInfo = parseUI5Types(oSetting.type, oAllDependentAPIs);
 							delete oSetting.type; // Keep file size in check
 						}
 
@@ -756,7 +767,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 						oEvent.parameters.forEach((oParameter) => {
 
 							if (oParameter.type) {
-								oParameter.typeInfo = parseUI5Types(oParameter.type);
+								oParameter.typeInfo = parseUI5Types(oParameter.type, oAllDependentAPIs);
 								delete oParameter.type; // Keep file size in check
 							}
 
@@ -789,7 +800,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 			if (oSymbol.methods) {
 
 				// Pre-process methods
-				methods.buildMethodsModel(oSymbol.methods);
+				methods.buildMethodsModel(oSymbol.methods, oAllDependentAPIs);
 
 				oSymbol.methods.forEach((oMethod) => {
 
@@ -950,6 +961,14 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	}
 
 	function loadDependencyLibraryFiles (oChainObject) {
+		const oAllDependentAPIs = oChainObject.oAllDependentAPIs = Object.create(null);
+		// add symbols from current library
+		if (oChainObject.fileData.symbols) {
+			for (const oSymbol of oChainObject.fileData.symbols) {
+				oAllDependentAPIs[oSymbol.name] = oSymbol;
+			}
+		}
+
 		if (!oChainObject.aDependentLibraryFiles) {
 			return oChainObject;
 		}
@@ -978,6 +997,12 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				// In this case we don't add it to the dependency list to skip double iteration.
 				if (oData && oChainObject.fileData.library !== oData.library) {
 					oDependentAPIs[oData.library] = oData.symbols;
+
+					if (Array.isArray(oData.symbols)) {
+						for (const oSymbol of oData.symbols) {
+							oAllDependentAPIs[oSymbol.name] = oSymbol;
+						}
+					}
 				}
 			});
 
@@ -987,22 +1012,69 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 	}
 
 	/**
-	 * Check for existence of FAQ data
-	 * (FAQ data must be defined as *.md files in the <code>sFAQDir</code>)
+	 * Check for existence of sections data
+	 * (Sections data must be defined as *.md files in the <code>sSectionsDir</code>)
 	 * and add a boolean flag in case it exists
 	 *
 	 * @param oChainObject chain object
 	 */
-	function addFlagsForFAQData(oChainObject) {
-		if (!sFAQDir) {
+	function addFlagsForSectionsData(oChainObject) {
+		if (!sSectionsDir) {
 			return oChainObject;
 		}
+
 		const slibName = oChainObject.fileData.library;
+
 		oChainObject.fileData.symbols.forEach(function(symbol) {
-			const sfile = symbol.name.replace(slibName, "").replace(/[.]/g, "/") + ".md";
-			if (fs.existsSync(path.join(sFAQDir, sfile))) {
-				symbol.hasFAQ = true;
+			const sComponentPath = symbol.name.replace(slibName, "").replace(/^[.]/, "").replace(/[.]/g, "/");
+			if (!sComponentPath) {
+				return;
 			}
+
+			const componentDir = path.join(sSectionsDir, sComponentPath);
+			if (fs.existsSync(componentDir)) {
+				try {
+				const dirContents = fs.readdirSync(componentDir, { withFileTypes: true });
+
+				// Separate files and directories in one pass
+				const mdFiles = [];
+				const dirNames = new Set();
+				dirContents.forEach((dirent) => {
+					if (dirent.isFile() && dirent.name.endsWith('.md')) {
+						mdFiles.push(dirent.name.replace(/\.md$/, ''));
+					} else if (dirent.isDirectory()) {
+						dirNames.add(dirent.name);
+					}
+				});
+
+				// Build customSections array with subsection support
+				const customSections = mdFiles.map(function(sectionName) {
+					// Check if there's a matching directory for this section
+					if (dirNames.has(sectionName)) {
+						try {
+							const subsectionFiles = fs.readdirSync(path.join(componentDir, sectionName), { withFileTypes: true })
+								.filter((dirent) => dirent.isFile() && dirent.name.endsWith('.md'))
+								.map((dirent) => dirent.name.replace(/\.md$/, ''));
+
+							if (subsectionFiles.length > 0) {
+								return { name: sectionName, hasSubsections: true, subsections: subsectionFiles };
+							}
+						} catch (error) {
+							log.error('Error scanning subsection directory:', path.join(componentDir, sectionName), error);
+						}
+					}
+					return sectionName;
+				});
+
+				if (customSections.length > 0) {
+					symbol.customSections = customSections;
+				}
+
+				} catch (error) {
+					log.error('Error scanning component sections directory:', componentDir, error);
+				}
+			}
+
 		});
 		return oChainObject;
 	}
@@ -2175,7 +2247,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		 * Adjusts methods info so that it can be easily displayed in a table
 		 * @param aMethods - the methods array initially coming from the server
 		 */
-		buildMethodsModel: function (aMethods) {
+		buildMethodsModel: function (aMethods, oAllDependentAPIs) {
 			var fnExtractParameterProperties = function (oParameter, aParameters, iDepth, aPhoneName) {
 				if (oParameter.parameterProperties) {
 					Object.keys(oParameter.parameterProperties).forEach(function (sProperty) {
@@ -2185,7 +2257,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 
 						// Handle types
 						if (oProperty.type) {
-							oProperty.typeInfo = parseUI5Types(oProperty.type);
+							oProperty.typeInfo = parseUI5Types(oProperty.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oProperty.type;
 						}
@@ -2217,7 +2289,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				if (oMethod.parameters) {
 					oMethod.parameters.forEach(function (oParameter) {
 						if (oParameter.type) {
-							oParameter.typeInfo = parseUI5Types(oParameter.type);
+							oParameter.typeInfo = parseUI5Types(oParameter.type, oAllDependentAPIs);
 							// Keep file size in check
 							delete oParameter.type;
 						}
@@ -2238,7 +2310,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 				// Handle return values
 				if (oMethod.returnValue && oMethod.returnValue.type) {
 					// Handle types
-					oMethod.returnValue.typeInfo = parseUI5Types(oMethod.returnValue.type);
+					oMethod.returnValue.typeInfo = parseUI5Types(oMethod.returnValue.type, oAllDependentAPIs);
 				}
 
 			});
@@ -2375,6 +2447,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		inputFile: sInputFile,
 		outputFile: sOutputFile,
 		libraryFile: sLibraryFile,
+		sectionsDir: sSectionsDir,
 		aDependentLibraryFiles: Array.isArray(vDependencyAPIFiles) ? vDependencyAPIFiles : null
 	};
 
@@ -2387,7 +2460,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		.then(getAPIJSONPromise)
 		.then(loadDependencyLibraryFiles)
 		.then(transformApiJson)
-		.then(addFlagsForFAQData)
+		.then(addFlagsForSectionsData)
 		.then(createApiRefApiJson);
 	return p;
 

package/lib/processors/jsdoc/lib/ui5/plugin.js

@@ -73,7 +73,8 @@ const path = require('jsdoc/path');
 const logger = require('jsdoc/util/logger');
 const pluginConfig = (env.conf && env.conf.templates && env.conf.templates.ui5) || env.opts.sapui5 || {};
 const escope = require("escope");
-const {isSemVer} = require("./template/utils/versionUtil");
+const templatePath = path.getResourcePath(env.opts.template) || "./template";
+const {isSemVer} = require(`${templatePath}/utils/versionUtil`);
 
 /* ---- logging ---- */
 
@@ -1220,11 +1221,13 @@ function collectClassInfo(extendCall, classDoclet) {
 	if ( classDoclet && classDoclet.augments && classDoclet.augments.length === 1 ) {
 		baseType = classDoclet.augments[0];
 	}
+	const jsdocClassName = classDoclet?.kind === "class" ? classDoclet.alias || classDoclet.longname : undefined;
+
 	if ( isMemberExpression(extendCall.callee) ) {
 		const baseCandidate = getResolvedObjectName(extendCall.callee.object);
 		if ( baseCandidate && baseType == null ) {
 			baseType = baseCandidate;
-		} else if ( baseCandidate !== baseType ) {
+		} else if ( baseCandidate !== toRuntimeMetadataName(baseType) ) {
 			future(`documented base type '${baseType}' doesn't match technical base type '${baseCandidate}'`);
 		}
 	}
@@ -1283,6 +1286,32 @@ function collectClassInfo(extendCall, classDoclet) {
 	}
 
 	const classInfoNode = extendCall.arguments[1];
+	if (classInfoNode?.type === Syntax.ObjectExpression && jsdocClassName && addLeadingCommentNode) {
+		// Take care of the @lends comment only
+		// - when the class info is an object literal (otherwise lends makes no sense)
+		// - when a class name is found (it might differ from the runtime metadata name)
+		// - when the entity is documented as a class (or else '.prototype' would be wrong)
+		const classInfoComment = getLeadingCommentNode(classInfoNode);
+		if (classInfoComment == null) {
+			// If the class info object doesn't have a @lends tag, add it
+			const raw = `/** @lends ${jsdocClassName}.prototype */`;
+			info(`lends comment injected for class '${jsdocClassName}'`);
+			addLeadingCommentNode(classInfoNode, {
+				type: "CommentBlock",
+				raw,
+				value: raw.slice(2,-2),
+				loc: classInfoNode.loc
+			});
+		} else {
+			// Otherwise check whether the name matches the name of the described class
+			const doclet = new Doclet(getRawComment(classInfoComment), {});
+			// The name after the @lends is surprisingly stored in the 'alias' property
+			if (doclet.alias !== `${jsdocClassName}.prototype`) {
+				future(`lends comment '${doclet.alias}' doesn't match documented class name '${jsdocClassName}'`);
+			}
+		}
+	}
+
 	const classInfoMap = createPropertyMap(classInfoNode);
 	if ( classInfoMap && classInfoMap.metadata && classInfoMap.metadata.value.type !== Syntax.ObjectExpression ) {
 		warning(`class metadata exists but can't be analyzed. It is not of type 'ObjectExpression', but a '${classInfoMap.metadata.value.type}'.`);
@@ -1772,7 +1801,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 	}
 
 	function name(prefix, n, _static) {
-		return oClassInfo.name + rname(prefix, n, _static);
+		return jsdocClassName + rname(prefix, n, _static);
 	}
 
 	/*
@@ -1884,6 +1913,18 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 	const p = m ? m.index : -1;
 	const hasSettingsDocs = rawClassComment.indexOf("The supported settings are:") >= 0;
 	const classAccess = doclet?.access ?? "public";
+
+	// If doclet exists and has an alias or longname, use that when building the fully qualified
+	// names of methods or events.
+	// Do this only when the doclet is of kind "class". Many TypeScript classes unfortunately
+	// use a broken pattern with @namespace (needs to be deprecated in babel-plugin-transform-modules-ui5)
+	const jsdocClassName =
+		(doclet?.kind === "class" ? doclet.alias || doclet.longname : undefined) || oClassInfo.name;
+	if (jsdocClassName !== oClassInfo.name) {
+		info("jsdoc class name differs from runtime metadata name", jsdocClassName, oClassInfo.name);
+	}
+
+	const displayClassName = oClassInfo.name;
 	const visibility = createVisibilityTags(classAccess, doclet?.__ui5?.stakeholders);
 	const thisClass = 'this'; // oClassInfo.name
 
@@ -2007,7 +2048,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 	}
 
 	newJSDoc([
-		"Returns a metadata object for class " + oClassInfo.name + ".",
+		"Returns a metadata object for class " + displayClassName + ".",
 		"",
 		"@returns {sap.ui.base.Metadata} Metadata object describing this class",
 		visibility,
@@ -2018,7 +2059,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 
 	if ( !oClassInfo["final"] ) {
 		newJSDoc([
-			"Creates a new subclass of class " + oClassInfo.name + " with name <code>sClassName</code>",
+			"Creates a new subclass of class " + displayClassName + " with name <code>sClassName</code>",
 			"and enriches it with the information contained in <code>oClassInfo</code>.",
 			"",
 			"<code>oClassInfo</code> might contain the same kind of information as described in {@link " + (oClassInfo.baseType ? oClassInfo.baseType + ".extend" : "sap.ui.base.Object.extend Object.extend") + "}.",
@@ -2304,7 +2345,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"",
 			info.enableEventBubbling ? "This event bubbles up the control hierarchy." : "",
 			"",
-			"@name " + oClassInfo.name + "#" + n,
+			"@name " + jsdocClassName + "#" + n,
 			"@event",
 			devStateTags,
 			"@param {sap.ui.base.Event} oControlEvent",
@@ -2321,10 +2362,10 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 		newJSDoc(lines);
 
 		newJSDoc([
-			"Attaches event handler <code>fnFunction</code> to the " + link + " event of this <code>" + oClassInfo.name + "</code>.",
+			"Attaches event handler <code>fnFunction</code> to the " + link + " event of this <code>" + displayClassName + "</code>.",
 			"",
 			"When called, the context of the event handler (its <code>this</code>) will be bound to <code>oListener</code> if specified, ",
-			"otherwise it will be bound to this <code>" + oClassInfo.name + "</code> itself.",
+			"otherwise it will be bound to this <code>" + displayClassName + "</code> itself.",
 			"",
 			!newStyle && info.doc ? info.doc : "",
 			"",
@@ -2333,7 +2374,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"@param {function(sap.ui.base.Event):void}",
 			"           fnFunction The function to be called when the event occurs",
 			"@param {object}",
-			"           [oListener] Context object to call the event handler with. Defaults to this <code>" + oClassInfo.name + "</code> itself",
+			"           [oListener] Context object to call the event handler with. Defaults to this <code>" + displayClassName + "</code> itself",
 			"",
 			"@returns {" + thisClass + "} Reference to <code>this</code> in order to allow method chaining",
 			devStateTags,
@@ -2342,7 +2383,7 @@ function createAutoDoc(oClassInfo, classComment, doclet, node, parser, filename,
 			"@function"
 		]);
 		newJSDoc([
-			"Detaches event handler <code>fnFunction</code> from the " + link + " event of this <code>" + oClassInfo.name + "</code>.",
+			"Detaches event handler <code>fnFunction</code> from the " + link + " event of this <code>" + displayClassName + "</code>.",
 			"",
 			"The passed function and listener object must match the ones used for event registration.",
 			"",
@@ -2439,6 +2480,7 @@ function toRuntimeMetadataName(longname) {
 
 let isDocComment;
 let getLeadingCommentNode;
+let addLeadingCommentNode;
 
 // JSDoc added the node type <code>Syntax.File</code> with the same change that activated Babylon
 // See https://github.com/jsdoc3/jsdoc/commit/ffec4a42291de6d68e6240f304b68d6abb82a869
@@ -2464,6 +2506,15 @@ if ( Syntax.File === 'File' ) {
 		return undefined;
 	};
 
+	addLeadingCommentNode = function(node, comment) {
+		node.leadingComments ??= [];
+		let index = node.leadingComments.length;
+		while (index > 0 && node.leadingComments[index - 1].type !== 'CommentBlock') {
+			index--;
+		}
+		node.leadingComments.splice(index, 0, comment);
+	}
+
 } else {
 
 	// JSDoc versions before 3.5.0
@@ -2498,6 +2549,9 @@ if ( Syntax.File === 'File' ) {
 
 		return comment;
 	};
+
+	// not implemented for espree (no automatic injection of @lends comments)
+	addLeadingCommentNode = undefined;
 }
 
 //--- comment related functions that are independent from the JSdoc version

package/lib/processors/jsdoc/lib/ui5/template/publish.js

@@ -231,6 +231,7 @@ function publish(symbolSet) {
 
 	// now resolve relationships
 	const aRootNamespaces = createNamespaceTree(allSymbols);
+	pushDownDeprecations(allSymbols);
 	createInheritanceTree(allSymbols);
 	collectMembers(allSymbols);
 	mergeEventDocumentation(allSymbols);
@@ -374,6 +375,33 @@ function makeNamespace(memberof) {
 	]);
 }
 
+function pushDownDeprecations() {
+
+	function pushDown(oSymbol, sInheritedDeprecation) {
+		if (oSymbol == null || !isFirstClassSymbol(oSymbol)) {
+			return;
+		}
+		const sOwnDeprecation = oSymbol.deprecated;
+		if (sOwnDeprecation == null && sInheritedDeprecation != null) {
+			oSymbol.deprecated = sInheritedDeprecation;
+			info(`mark ${oSymbol.longname} as deprecated (${sInheritedDeprecation})`);
+		} else if (sOwnDeprecation != null) {
+			const info = extractSince(sOwnDeprecation);
+			const sinceBecause = info.since ? `As of version ${info.since}, because`: `Because`;
+			sInheritedDeprecation = `${sinceBecause} it is part of the deprecated package ${oSymbol.longname}`;
+		}
+		oSymbol.__ui5.children?.forEach((oChild) => pushDown(oChild, sInheritedDeprecation));
+	}
+
+	// w/o a library name we can't start with the library namespace
+	if (!templateConf.uilib) {
+		return;
+	}
+
+	// start the push down at the library namespace to ensure locality
+	pushDown(lookup(templateConf.uilib));
+}
+
 //---- inheritance hierarchy ----------------------------------------------------------------------------
 
 /*

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ui5/builder",
-	"version": "4.1.4",
+	"version": "4.1.6",
 	"description": "UI5 CLI - Builder",
 	"author": {
 		"name": "SAP SE",
@@ -134,7 +134,7 @@
 		"less-openui5": "^0.11.6",
 		"pretty-data": "^0.40.0",
 		"semver": "^7.7.4",
-		"terser": "^5.46.0",
+		"terser": "^5.46.1",
 		"workerpool": "^9.3.4",
 		"xml2js": "^0.6.2"
 	},
@@ -142,23 +142,23 @@
 		"@eslint/js": "^9.14.0",
 		"@istanbuljs/esm-loader-hook": "^0.3.0",
 		"@jridgewell/trace-mapping": "^0.3.31",
-		"@ui5/project": "^4.0.9",
+		"@ui5/project": "^4.0.15",
 		"ava": "^6.4.1",
 		"chokidar-cli": "^3.0.0",
 		"cross-env": "^10.1.0",
 		"docdash": "^2.0.2",
-		"eslint": "^9.39.2",
+		"eslint": "^9.39.4",
 		"eslint-config-google": "^0.14.0",
 		"eslint-plugin-ava": "^15.1.0",
 		"eslint-plugin-jsdoc": "61.5.0",
 		"esmock": "^2.7.3",
 		"globals": "^16.5.0",
-		"knip": "^5.83.1",
+		"knip": "^5.88.1",
 		"line-column": "^1.0.2",
 		"nyc": "^17.1.0",
 		"open-cli": "^8.0.0",
 		"rimraf": "^6.1.3",
-		"sinon": "^21.0.1",
+		"sinon": "^21.1.2",
 		"tap-xunit": "^2.4.1"
 	}
 }