@ui5/webcomponents-tools 0.0.0-f1f9d888f → 0.0.0-f24ff9019

package/lib/hbs2ui5/index.js

@@ -1,10 +1,12 @@
-const fs = require('fs');
+const fs = require('fs').promises;
+const existsSync = require('fs').existsSync;
 const getopts = require('getopts');
 const hbs2lit = require('../hbs2lit');
 const path = require('path');
 const litRenderer = require('./RenderTemplates/LitRenderer');
 const recursiveReadDir = require("recursive-readdir");
-const mkdirp = require('mkdirp');
+
+let missingTypesReported = false;
 
 const args = getopts(process.argv.slice(2), {
 	alias: {
@@ -24,13 +26,27 @@ const onError = (place) => {
 
 const isHandlebars = (fileName) => fileName.indexOf('.hbs') !== -1;
 
-const processFile = (file, outputDir) => {
-	const litCode = hbs2lit(file);
-	const absoluteOutputDir = composeAbsoluteOutputDir(file, outputDir);
+const hasTypes = (file, componentName) => {
+	const tsFile = path.join(path.dirname(file), componentName + ".ts")
+	const dtsFile = path.join(path.dirname(file), componentName + ".d.ts")
+	return existsSync(tsFile) || existsSync(dtsFile);
+}
+
+const processFile = async (file, outputDir) => {
 	const componentNameMatcher = /(\w+)(\.hbs)/gim;
 	const componentName = componentNameMatcher.exec(file)[1];
+	const componentHasTypes = hasTypes(file, componentName);
+	if (!componentHasTypes) { 
+		if (!missingTypesReported) {
+			console.warn("[Warn] The following templates do not have a corresponging .ts or .d.ts file and won't be type checked:")
+			missingTypesReported = true;
+		}
+		console.log("  -> " + componentName + ".hbs");
+	}
+	const litCode = await hbs2lit(file, componentName);
+	const absoluteOutputDir = composeAbsoluteOutputDir(file, outputDir);
 
-	writeRenderers(absoluteOutputDir, componentName, litRenderer.generateTemplate(componentName, litCode));
+	return writeRenderers(absoluteOutputDir, componentName, litRenderer.generateTemplate(componentName, litCode, componentHasTypes));
 };
 
 const composeAbsoluteOutputDir = (file, outputDir) => {
@@ -40,39 +56,54 @@ const composeAbsoluteOutputDir = (file, outputDir) => {
 	const fileDir = file.split(path.sep).slice(1, -1).join(path.sep);
 
 	// (2) Compose full output dir - "dist/generated/templates/lvl1/lvl2"
-	return `${outputDir}${path.sep}${fileDir}`; 
+	return `${outputDir}${path.sep}${fileDir}`;
 };
 
 const wrapDirectory = (directory, outputDir) => {
 	directory = path.normalize(directory);
 	outputDir = path.normalize(outputDir);
 
-	recursiveReadDir(directory, (err, files) => {
-
-		if (err) {
-			onError('directory');
-		}
+	return new Promise((resolve, reject) => {
+		recursiveReadDir(directory, (err, files) => {
 
-		files.forEach(fileName => {
-			if (isHandlebars(fileName)) {
-				processFile(fileName, outputDir);
+			if (err) {
+				onError('directory');
+				reject();
 			}
+
+			const promises = files.map(fileName => {
+				if (isHandlebars(fileName)) {
+					return processFile(fileName, outputDir);
+				}
+			}).filter(x => !!x);
+
+			resolve(Promise.all(promises));
 		});
-	})
+	});
 };
 
-const writeRenderers = (outputDir, controlName, fileContent) => {
+const writeRenderers = async (outputDir, controlName, fileContent) => {
 	try {
-		if (!fs.existsSync(outputDir)) {
-			mkdirp.sync(outputDir);
-		}
 
-		const compiledFilePath = `${outputDir}${path.sep}${controlName}Template.lit.js`;
+		await fs.mkdir(outputDir, { recursive: true });
+
+		const compiledFilePath = `${outputDir}${path.sep}${controlName}Template.lit.${process.env.UI5_TS ? "ts" : "js"}`;
 
 		// strip DOS line endings because the break the source maps
 		let fileContentUnix = fileContent.replace(/\r\n/g, "\n");
 		fileContentUnix = fileContentUnix.replace(/\r/g, "\n");
-		fs.writeFileSync(compiledFilePath, fileContentUnix);
+
+		// Only write to the file system actual changes - each updated file, no matter if the same or not, triggers an expensive operation for rollup
+		// Note: .hbs files that include a changed .hbs file will also be recompiled as their content will be updated too
+
+		let existingFileContent = "";
+		try {
+			existingFileContent = await fs.readFile(compiledFilePath);
+		} catch (e) {}
+
+		if (existingFileContent !== fileContentUnix) {
+			return fs.writeFile(compiledFilePath, fileContentUnix);
+		}
 
 	} catch (e) {
 		console.log(e);
@@ -82,5 +113,7 @@ const writeRenderers = (outputDir, controlName, fileContent) => {
 if (!args['d'] || !args['o']) {
 	console.log('Please provide an input and output directory (-d and -o)');
 } else {
-	wrapDirectory(args['d'], args['o']);
+	wrapDirectory(args['d'], args['o']).then(() => {
+		console.log("Templates generated");
+	});
 }

package/lib/i18n/defaults.js

@@ -1,74 +1,82 @@
-const fs = require('fs');
+const fs = require('fs').promises;
 const path = require('path');
 const PropertiesReader = require('properties-reader');
-const mkdirp = require("mkdirp");
 const assets = require('../../assets-meta.js');
 
-const defaultLanguage = assets.languages.default;
+const generate = async () => {
+	const defaultLanguage = assets.languages.default;
 
-const messageBundle = path.normalize(`${process.argv[2]}/messagebundle.properties`);
-const messageBundleDefaultLanguage = path.normalize(`${process.argv[2]}/messagebundle_${defaultLanguage}.properties`);
-const outputFile = path.normalize(`${process.argv[3]}/i18n-defaults.js`);
+	const messageBundle = path.normalize(`${process.argv[2]}/messagebundle.properties`);
+	const messageBundleDefaultLanguage = path.normalize(`${process.argv[2]}/messagebundle_${defaultLanguage}.properties`);
+	const tsMode = process.env.UI5_TS === "true"; // In Typescript mode, we output .ts files and set the required types, otherwise - output pure .js files
 
-if (!messageBundle || !outputFile) {
-	return;
-}
+	const outputFile = path.normalize(`${process.argv[3]}/i18n-defaults.${tsMode ? "ts": "js"}`);
 
-const properties = PropertiesReader(messageBundle)._properties;
+	if (!messageBundle || !outputFile) {
+		return;
+	}
 
-let defaultLanguageProperties;
-try {
-	defaultLanguageProperties = PropertiesReader(messageBundleDefaultLanguage)._properties;
-}
-catch (e) {}
+	const properties = PropertiesReader(messageBundle)._properties;
 
+	let defaultLanguageProperties;
+	try {
+		defaultLanguageProperties = PropertiesReader(messageBundleDefaultLanguage)._properties;
+	} catch (e) {
+	}
 
-/*
- * Returns the single text object to enable single export.
- *
- * Example:
- * const ARIA_LABEL_CARD_CONTENT = {
- *	key: "ARIA_LABEL_CARD_CONTENT",
- *	defaultText: "Card Content",
- * };
- */
-const getTextInfo = (key, value, defaultLanguageValue) => {
-	let effectiveValue = defaultLanguageValue || value;
-	effectiveValue = effectiveValue.replace(/\"/g, "\\\""); // escape double quotes in translations
+	// Merge messagebundle.properties and messagebundle_en.properties files to generate the default texts.
+	// Note:
+	// (1) at DEV time, it's intuituve to work with the source bundle file - the messagebundle.properties,
+	// and see the changes there take effect.
+	// (2) as the messagebundle.properties file is always written in English,
+	// it makes sense to consider the messagebundle.properties content only when the default language is "en".
+	if (defaultLanguage === "en") {
+		defaultLanguageProperties = Object.assign({}, defaultLanguageProperties, properties);  
+	}
 
-	return `const ${key} = {key: "${key}", defaultText: "${effectiveValue}"};`;
-};
+	/*
+	 * Returns the single text object to enable single export.
+	 *
+	 * Example:
+	 * const ARIA_LABEL_CARD_CONTENT = {
+	 *	key: "ARIA_LABEL_CARD_CONTENT",
+	 *	defaultText: "Card Content",
+	 * };
+	 */
+	const getTextInfo = (key, value, defaultLanguageValue) => {
+		let effectiveValue = defaultLanguageValue || value;
+		effectiveValue = effectiveValue.replace(/\"/g, "\\\""); // escape double quotes in translations
 
-/*
- * Returns the complete content of i18n-defaults.js file:
- * (1) the single text objects
- * (2) the export statement at the end of the file
- *
- * Example:
- * export {
- *	ARIA_LABEL_CARD_CONTENT,
- * }
- */
-const getOutputFileContent = (properties, defaultLanguageProperties) => {
-	const textKeys = Object.keys(properties);
-	const texts = textKeys.map(prop => getTextInfo(prop, properties[prop], defaultLanguageProperties && defaultLanguageProperties[prop])).join('');
+		if (tsMode) {
+			return `const ${key}: I18nText = {key: "${key}", defaultText: "${effectiveValue}"};`;
+		}
+		return `const ${key} = {key: "${key}", defaultText: "${effectiveValue}"};`;
+	};
 
-	return `${texts}
-export {${textKeys.join()}};`;
-};
+	/*
+	 * Returns the complete content of i18n-defaults.js file:
+	 * (1) the single text objects
+	 * (2) the export statement at the end of the file
+	 *
+	 * Example:
+	 * export {
+	 *	ARIA_LABEL_CARD_CONTENT,
+	 * }
+	 */
+	const getOutputFileContent = (properties, defaultLanguageProperties) => {
+		const textKeys = Object.keys(properties);
+		const texts = textKeys.map(prop => getTextInfo(prop, properties[prop], defaultLanguageProperties && defaultLanguageProperties[prop])).join('');
 
-/*
- * Writes the i18n-defaults.js.
- */
-const writeI18nDefaultsFile = (file, content) => {
-	fs.writeFile(file, content, (err) => {
-		if (err) {
-			return console.log(err);
-		}
+		// tabs are intentionally mixed to have proper identation in the produced file
+		return `${tsMode ? `import { I18nText } from "@ui5/webcomponents-base/dist/i18nBundle.js";` : ""}
+${texts}
+export {${textKeys.join()}};`;
+	};
 
-		console.log(`[i18n]: "${file}" file has been created`);
-	});
+	await fs.mkdir(path.dirname(outputFile), { recursive: true });
+	await fs.writeFile(outputFile, getOutputFileContent(properties, defaultLanguageProperties));
 };
 
-mkdirp.sync(path.dirname(outputFile));
-writeI18nDefaultsFile(outputFile, getOutputFileContent(properties, defaultLanguageProperties));
+generate().then(() => {
+	console.log("i18n default file generated.");
+});

package/lib/i18n/toJSON.js

@@ -8,18 +8,16 @@
  * The 2nd param './../dist/generated/assets/i18n' is where the JSON files would be written to.
  */
 const path = require("path");
-const glob = require("glob");
 const PropertiesReader = require('properties-reader');
-const fs = require('fs');
+const fs = require('fs').promises;
 const assets = require('../../assets-meta.js');
-const mkdirp = require("mkdirp");
 
 const allLanguages = assets.languages.all;
 
 const messagesBundles = path.normalize(`${process.argv[2]}/messagebundle_*.properties`);
 const messagesJSONDist = path.normalize(`${process.argv[3]}`);
 
- const convertToJSON = (file) => {
+const convertToJSON = async (file) => {
 	const properties = PropertiesReader(file)._properties;
 	const filename = path.basename(file, path.extname(file));
 	const language = filename.match(/^messagebundle_(.*?)$/)[1];
@@ -29,14 +27,17 @@ const messagesJSONDist = path.normalize(`${process.argv[3]}`);
 	}
 	const outputFile = path.normalize(`${messagesJSONDist}/${filename}.json`);
 
-	fs.writeFileSync(outputFile, JSON.stringify(properties));
-	console.log(`[i18n]: "${filename}.json" has been generated!`);
+	return fs.writeFile(outputFile, JSON.stringify(properties));
+	// console.log(`[i18n]: "${filename}.json" has been generated!`);
 };
 
-mkdirp.sync(messagesJSONDist);
- glob(messagesBundles, {}, (err, files) => {
-	if (err) {
-		return console.log("No messagebundle files found!");
-	}
-	files.forEach(convertToJSON);
+const generate = async () => {
+	const { globby } = await import("globby");
+	await fs.mkdir(messagesJSONDist, { recursive: true });
+	const files = await globby(messagesBundles.replace(/\\/g, "/"));
+	return Promise.all(files.map(convertToJSON));
+};
+
+generate().then(() => {
+	console.log("Message bundle JSON files generated.");
 });

package/lib/jsdoc/configTypescript.json

@@ -0,0 +1,29 @@
+{
+	"source": {
+		"include": "jsdoc-dist",
+		"excludePattern": "(/|\\\\)library-all\\.js|(/|\\\\).*-preload\\.js|^jquery-.*\\.js|^sap-.*\\.js|.+Renderer\\.lit\\.js|.*library\\.js|thirdparty"
+	},
+	"opts" : {
+		"recurse": true,
+		"template" : "template",
+		"destination": ""
+	},
+	"plugins": [
+		"./plugin.js"
+	],
+	"templates" : {
+		"ui5" : {
+			"variants": [
+				"apijson"
+			],
+			"version": "1.62",
+			"apiJsonFolder": "",
+			"apiJsonFile": "dist/api.json",
+			"includeSettingsInConstructor": false
+		}
+	},
+	"tags": {
+		"allowUnknownTags": true,
+		"dictionaries": ["jsdoc"]
+	}
+}

package/lib/jsdoc/plugin.js

@@ -31,6 +31,16 @@
  *
  *   tagname
  *
+ *   native
+ *
+ *   noattribute
+ * 
+ *   formEvents
+ * 
+ *   formProperty
+ *
+ *   allowPreventDefault
+ *
  * It furthermore listens to the following JSDoc3 events to implement additional functionality
  *
  *   parseBegin
@@ -2060,9 +2070,11 @@ exports.defineTags = function(dictionary) {
 	});
 
 	dictionary.defineTag('slot', {
-		mustNotHaveValue: true,
 		onTagged: function(doclet, tag) {
 			doclet.slot = true;
+			if (tag.value) {
+				doclet.propertyName = tag.value;
+			}
 		}
 	});
 
@@ -2079,6 +2091,55 @@ exports.defineTags = function(dictionary) {
 			doclet.tagname = tag.value;
 		}
 	});
+
+	dictionary.defineTag('allowPreventDefault', {
+		mustHaveValue: false,
+		onTagged: function(doclet, tag) {
+			doclet.allowPreventDefault = true;
+		}
+	});
+
+	dictionary.defineTag('native', {
+		mustHaveValue: false,
+		onTagged: function(doclet, tag) {
+			doclet.native = true;
+		}
+	});
+
+	dictionary.defineTag('noattribute', {
+		mustHaveValue: false,
+		onTagged: function(doclet, tag) {
+			doclet.noattribute = true;
+		}
+	});
+
+	dictionary.defineTag('formEvents', {
+		mustHaveValue: false,
+		onTagged: function(doclet, tag) {
+			if (tag.value) {
+				doclet.formEvents = doclet.formEvents || [];
+				tag.value.split(" ").forEach(function($) {
+					if ( doclet.formEvents.indexOf($) < 0 ) {
+						doclet.formEvents.push($);
+					}
+				});
+			}
+		}
+	});
+
+	dictionary.defineTag('formProperty', {
+		mustHaveValue: false,
+		onTagged: function(doclet, tag) {
+			doclet.formProperty = true;
+		}
+	});
+
+	dictionary.defineTag('formAssociated', {
+		mustHaveValue: false,
+		onTagged: function(doclet, tag) {
+			doclet.formAssociated = doclet.formAssociated || true;
+		}
+	});
 };
 
 exports.handlers = {

package/lib/jsdoc/preprocess.js

@@ -0,0 +1,146 @@
+const process = require("process");
+const path = require("path");
+const fs = require("fs/promises");
+
+const inputDir = process.argv[2];
+const sourceDir = process.argv[3];
+
+const preprocessTypes = async () => {
+	try {
+		const { globby } = await import("globby");
+		const fileNames = await globby(inputDir.replace(/\\/g, "/") + "**/types/*.js");
+
+		return Promise.all(fileNames.map(processTypeFile));
+	} catch(e) {
+		console.log("JSDoc types preprocess failed: ", e);
+	}
+};
+
+const processTypeFile = async (fileName) => {
+	let fileContent = `${await fs.readFile(fileName)}`;
+
+	const re = new RegExp(`(\\/\\*\\*\\s*\\n([^\\*]|(\\*(?!\\/)))*\\*\\/)\\s+[\\w\\d]+\\[\\"([\\w\\d]+)\\"\\]\\s*=\\s*\\"([\\w\\d]+)\\";`, "gm")
+	let matches = [...fileContent.matchAll(re)];
+
+	// Get all type values
+	const typeData = matches.map(match => {
+		return {
+			comment: match[1],
+			key: match[4],
+			value: match[5],
+		};
+	});
+	if (typeData.length === 0) {
+		return;
+	}
+
+	const typeName = path.parse(fileName).name;
+
+	matches = fileContent.match(/\/\*\*\s*\n([^\*]|(\*(?!\/)))*\*\//gm);
+	const comment = matches[0];
+
+	const propsCode = typeData.map(item => {
+		return `${item.comment}\n get ${item.key}() { return "${item.value}"; }`;
+	}).join("\n");
+
+	const newClassCode = `
+	${comment}
+	class ${typeName} {
+		${propsCode}
+	};
+
+	export default ${typeName};`;
+
+	fileContent = newClassCode;
+
+	return fs.writeFile(fileName, fileContent);
+};
+
+const preprocessComponents = async () => {
+	if (!sourceDir) {
+		return; // if the second param was not passed, there are no components
+	}
+
+	try {
+		const { globby } = await import("globby");
+		const fileNames = await globby(sourceDir.replace(/\\/g, "/") + "/*.ts");
+
+		return Promise.all(fileNames.map(processComponentFile));
+	} catch(e) {
+		console.log("JSDoc components preprocess failed: ", e);
+	}
+};
+
+const isClass = text => {
+	return text.includes("@abstract") || text.includes("@class");
+};
+
+const isAnnotationComment = (comment) =>  {
+	return comment.includes("@name");
+}
+
+const processComponentFile = async (fileName) => {
+	// source file (src/*.ts)
+	let tsFileContent = `${await fs.readFile(fileName)}`;
+
+	// Skip all non-component files
+	if (!isClass(tsFileContent)) {
+		return;
+	}
+
+	// Gather all JSDocs from the original .ts file
+	const allJSDocsRegExp = new RegExp(`\\/\\*\\*(.|\\n)+?\\s+\\*\\/`, "gm");
+	let allJSDocs = [...tsFileContent.matchAll(allJSDocsRegExp)];
+	allJSDocs = allJSDocs.map(match => match[0]); // all /** ..... */ comments
+
+	// Find where the class is defined in the original file
+	const tsClassDefinitionRegExp = new RegExp(`^(abstract\\s)?class [\\w\\d_]+`, "gm");
+	let tsClassDefinitionMatch = tsFileContent.match(tsClassDefinitionRegExp);
+	if (!tsClassDefinitionMatch) {
+		return; // no class defined in this .ts file
+	}
+	const tsClassDefinition = tsClassDefinitionMatch[0];
+	const tsClassDefinitionIndex = tsFileContent.indexOf(tsClassDefinition);
+
+	// Gather all JSDocs that are before the class definition (except for the @class one)
+	const JSDocsToAppend = [];
+	allJSDocs.forEach(JSDoc => {
+		if (!isClass(JSDoc) && (tsFileContent.indexOf(JSDoc) < tsClassDefinitionIndex || isAnnotationComment(JSDoc, tsFileContent))) {
+			JSDocsToAppend.push(JSDoc);
+		}
+	});
+
+
+
+	// destination file (jsdoc-dist/*.js)
+	const destFileName = fileName.replace(sourceDir, inputDir).replace(/\.ts$/, ".js");
+	let jsFileContent = `${await fs.readFile(destFileName)}`;
+
+	const classDefinitionRegExp = new RegExp(`let.*? = class`, "gm");
+	let classDefinitionMatch = jsFileContent.match(classDefinitionRegExp);
+	if (!classDefinitionMatch) {
+		return; // not a file, generated by typescript, nothing to do here
+	}
+
+	const classDefinition = classDefinitionMatch[0];
+	const classDefinitionIndex = jsFileContent.indexOf(classDefinition); // classDefinitionIndex is the position in the file where the class is defined
+
+	// All comments before the class definition, except for the @class comment, must be removed
+	allJSDocs.forEach(JSDoc => {
+		if (!isClass(JSDoc) && jsFileContent.indexOf(JSDoc) < classDefinitionIndex) {
+			jsFileContent = jsFileContent.replace(JSDoc, "");
+		}
+	});
+
+	// Put all other comments at the end of the file
+	jsFileContent = jsFileContent + "\n\n" + JSDocsToAppend.join("\n\n");
+	return fs.writeFile(destFileName, jsFileContent);
+};
+
+Promise.all([
+	preprocessTypes(),
+	preprocessComponents(),
+]).then(() => {
+	console.log("JSDoc preprocess ready.");
+});
+

package/lib/jsdoc/template/publish.js

@@ -2804,6 +2804,10 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 						attrib("export", undefined, '', true);
 					}
 
+					if (member.noattribute) {
+						attrib("noattribute", true);
+					}
+
 					if (member.readonly) {
 						attrib("readonly", member.readonly, null);
 					}
@@ -2815,7 +2819,22 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 					if ( member.since ) {
 						attrib("since", extractVersion(member.since));
 					}
-					attrib("type", listTypes(member.type));
+
+					if ( member.formEvents ) {
+						attrib("formEvents", member.formEvents);
+					}
+
+					if ( member.formEvents ) {
+						attrib("formProperty", member.formProperty);
+					}
+
+					var type = listTypes(member.type);
+					attrib("type", type);
+
+					if ((type === "object" || type === "Object") && visibility(member) === "public") {
+						attrib("noattribute", true);
+					}
+
 					tag("description", normalizeWS(member.description), true);
 					if (member.defaultvalue) {
 						attrib("defaultValue", member.defaultvalue);
@@ -2838,6 +2857,9 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 				if (member.slot) {
 					tag("property");
 					attrib("name", member.name);
+					if (member.propertyName) {
+						attrib("propertyName", member.propertyName);
+					}
 					if (member.__ui5.module && member.__ui5.module !== symbol.__ui5.module) {
 						attrib("module", member.__ui5.module);
 						attrib("export", undefined, '', true);
@@ -2879,6 +2901,12 @@ function createAPIJSON4Symbol(symbol, omitDefaults) {
 					attrib("module", member.__ui5.module);
 					attrib("export", undefined, '', true);
 				}
+				if (member.allowPreventDefault) {
+					attrib("allowPreventDefault", true);
+				}
+				if (member.native) {
+					attrib("native", true);
+				}
 				attrib("visibility", visibility(member), 'public');
 				if ( member.scope === 'static' ) {
 					attrib("static", true, false, /* raw = */true);
@@ -3845,7 +3873,7 @@ function createAPIJS(symbols, filename) {
 
 	var output = [];
 
-	var rkeywords = /^(?:abstract|as|boolean|break|byte|case|catch|char|class|continue|const|debugger|default|delete|do|double|else|enum|export|extends|false|final|finally|float|for|function|goto|if|implements|import|in|instanceof|int|interface|is|long|namespace|native|new|null|package|private|protected|public|return|short|static|super|switch|synchronized|this|throw|throws|transient|true|try|typeof|use|var|void|volatile|while|with)$/;
+	var rkeywords = /^(?:abstract|as|boolean|break|byte|case|catch|char|class|continue|const|debugger|default|delete|do|double|else|enum|export|extends|false|final|finally|float|for|function|formEvents|formProperty|goto|if|implements|import|in|instanceof|int|interface|is|long|namespace|native|new|null|noattribute|package|private|protected|public|return|short|static|super|switch|synchronized|this|throw|throws|transient|true|try|typeof|use|var|void|volatile|while|with)$/;
 
 	function isNoKeyword($) { return !rkeywords.test($.name); }