feat(builder): Add dynamic section for API reference during JSDoc build

Enables automatic discovery and rendering of documentation sections (FAQ, guides, etc.) from directory structure. Sections are discovered at build time and loaded asynchronously at runtime.

JIRA: BGSOFUIPIRIN-6925
Cherry-picked from UI5/openui5@c71a404cb.

Author: codeworrior

packages/builder/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.");
 	}
@@ -987,22 +987,43 @@ 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 customSections = fs.readdirSync(componentDir, { withFileTypes: true })
+						.filter((dirent) => dirent.isFile() && dirent.name.endsWith('.md'))
+						.map((dirent) => dirent.name.replace(/\.md$/, ''));
+
+					// Store list of available sections for this symbol
+					if (customSections.length > 0) {
+						symbol.customSections = customSections;
+					}
+
+				} catch (error) {
+					log.error('Error scanning component sections directory:', componentDir, error);
+				}
+			}
+
 		});
 		return oChainObject;
 	}
@@ -2375,6 +2396,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		inputFile: sInputFile,
 		outputFile: sOutputFile,
 		libraryFile: sLibraryFile,
+		sectionsDir: sSectionsDir,
 		aDependentLibraryFiles: Array.isArray(vDependencyAPIFiles) ? vDependencyAPIFiles : null
 	};
 
@@ -2387,7 +2409,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 		.then(getAPIJSONPromise)
 		.then(loadDependencyLibraryFiles)
 		.then(transformApiJson)
-		.then(addFlagsForFAQData)
+		.then(addFlagsForSectionsData)
 		.then(createApiRefApiJson);
 	return p;