@ui5/webcomponents-tools 0.0.0-fca1107e7 → 0.0.0-fd426fe8a

package/icons-collection/nps.js

@@ -41,8 +41,8 @@ const copyIconAssetsCommand = (options) => {
 const getScripts = (options) => {
 	const createJSImportsCmd = createIconImportsCommand(options);
 	const copyAssetsCmd = copyIconAssetsCommand(options);
-	const tsCommand = options.typescript ? "tsc --build" : "";
-	const tsCrossEnv = options.typescript ? "cross-env UI5_TS=true" : "";
+	const tsCommand = !options.legacy ? "tsc --build" : "";
+	const tsCrossEnv = !options.legacy ? "cross-env UI5_TS=true" : "";
 
 	const scripts = {
 		clean: "rimraf dist && rimraf src/generated",

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

@@ -4,6 +4,7 @@ import path from "path";
 import fs from 'fs';
 import {
 	getDeprecatedStatus,
+	getExperimentalStatus,
 	getSinceStatus,
 	getPrivacyStatus,
 	getReference,
@@ -26,6 +27,7 @@ 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"));
+const devMode = process.env.UI5_CEM_MODE === "dev";
 
 const extractClassNodeJSDoc = node => {
 	const fileContent = node.getFullText();
@@ -64,12 +66,23 @@ function processClass(ts, classNode, moduleDoc) {
 	currClass.customElement = !!customElementDecorator || className === "UI5Element" || undefined;
 	currClass.kind = "class";
 	currClass.deprecated = getDeprecatedStatus(classParsedJsDoc);
+	currClass._ui5experimental = getExperimentalStatus(classParsedJsDoc);
 	currClass._ui5since = getSinceStatus(classParsedJsDoc);
 	currClass._ui5privacy = getPrivacyStatus(classParsedJsDoc);
 	currClass._ui5abstract = hasTag(classParsedJsDoc, "abstract") ? true : undefined;
 	currClass.description = normalizeDescription(classParsedJsDoc.description || findTag(classParsedJsDoc, "class")?.description);
 	currClass._ui5implements = findAllTags(classParsedJsDoc, "implements")
-		.map(tag => getReference(ts, normalizeTagType(tag.type), classNode, moduleDoc.path))
+		.map(tag => {
+			const correctInterfaceDescription = classNode?.heritageClauses?.some(heritageClause => {
+				return heritageClause?.types?.some(type => type.expression?.text === normalizeTagType(tag.type));
+			});
+
+			if (!correctInterfaceDescription) {
+				logDocumentationError(moduleDoc.path, `@interface {${tag.type}} tag is used, but the class doesn't implement the corresponding interface`)
+			}
+
+			return getReference(ts, normalizeTagType(tag.type), classNode, moduleDoc.path)
+		})
 		.filter(Boolean);
 
 
@@ -77,6 +90,10 @@ function processClass(ts, classNode, moduleDoc) {
 		const superclassTag = findTag(classParsedJsDoc, "extends");
 		currClass.superclass = getReference(ts, superclassTag.name, classNode, moduleDoc.path);
 
+		if (classNode?.heritageClauses?.[0]?.types?.[0]?.expression?.text !== superclassTag.name) {
+			logDocumentationError(moduleDoc.path, `@extends ${superclassTag.name} is used, but the class doesn't extend the corresponding superclass`)
+		}
+
 		if (currClass.superclass?.name === "UI5Element") {
 			currClass.customElement = true;
 		}
@@ -111,9 +128,13 @@ function processClass(ts, classNode, moduleDoc) {
 	}
 
 	// Events
-	currClass.events = findAllDecorators(classNode, "event")
+	currClass.events = findAllDecorators(classNode, ["event", "eventStrict"])
 		?.map(event => processEvent(ts, event, classNode, moduleDoc));
 
+	const filename = classNode.getSourceFile().fileName;
+	const sourceFile = typeProgram.getSourceFile(filename);
+	const tsProgramClassNode = sourceFile.statements.find(statement => ts.isClassDeclaration(statement) && statement.name?.text === classNode.name?.text);
+
 	// Slots (with accessor), methods and fields
 	for (let i = 0; i < (currClass.members?.length || 0); i++) {
 		const member = currClass.members[i];
@@ -168,17 +189,21 @@ function processClass(ts, classNode, moduleDoc) {
 				const propertyDecorator = findDecorator(classNodeMember, "property");
 
 				if (propertyDecorator) {
-					member._ui5validator = propertyDecorator?.expression?.arguments[0]?.properties?.find(property => ["validator", "type"].includes(property.name.text))?.initializer?.text || "String";
 					member._ui5noAttribute = propertyDecorator?.expression?.arguments[0]?.properties?.find(property => property.name.text === "noAttribute")?.initializer?.kind === ts.SyntaxKind.TrueKeyword || undefined;
 				}
 
-				if (currClass.customElement && member.privacy === "public" && !propertyDecorator?.expression?.arguments[0]?.properties?.find(property => property.name.text === "multiple") && !["object"].includes(member._ui5validator?.toLowerCase())) {
-					const filename = classNode.getSourceFile().fileName;
-					const sourceFile = typeProgram.getSourceFile(filename);
-					const tsProgramClassNode = sourceFile.statements.find(statement => ts.isClassDeclaration(statement) && statement.name?.text === classNode.name?.text);
+				if (currClass.customElement && member.privacy === "public") {
 					const tsProgramMember = tsProgramClassNode.members.find(m => ts.isPropertyDeclaration(m) && m.name?.text === member.name);
 					const attributeValue = typeChecker.typeToString(typeChecker.getTypeAtLocation(tsProgramMember), tsProgramMember);
 
+					if (attributeValue === "boolean" && member.default === "true") {
+						logDocumentationError(moduleDoc.path, `Boolean properties must be initialzed to false. [${member.name}] property of class [${className}] is intialized to \`true\``)
+					}
+
+					if (!member.type) {
+						logDocumentationError(moduleDoc.path, `Public properties must have type. The type of [${member.name}] property is not determinated automatically. Please check it.`)
+					}
+
 					currClass.attributes.push({
 						description: member.description,
 						name: toKebabCase(member.name),
@@ -293,6 +318,7 @@ function processInterface(ts, interfaceNode, moduleDoc) {
 		kind: "interface",
 		name: interfaceName,
 		description: normalizeDescription(interfaceParsedJsDoc?.description),
+		_ui5experimental: getExperimentalStatus(interfaceParsedJsDoc),
 		_ui5privacy: getPrivacyStatus(interfaceParsedJsDoc),
 		_ui5since: getSinceStatus(interfaceParsedJsDoc),
 		deprecated: getDeprecatedStatus(interfaceParsedJsDoc),
@@ -313,6 +339,7 @@ function processEnum(ts, enumNode, moduleDoc) {
 		kind: "enum",
 		name: enumName,
 		description: normalizeDescription(enumJSdoc?.comment),
+		_ui5experimental: getExperimentalStatus(enumParsedJsDoc),
 		_ui5privacy: getPrivacyStatus(enumParsedJsDoc),
 		_ui5since: getSinceStatus(enumParsedJsDoc),
 		deprecated: getDeprecatedStatus(enumParsedJsDoc) || undefined,
@@ -425,14 +452,6 @@ export default {
 				}
 			},
 			moduleLinkPhase({ moduleDoc }) {
-				for (let i = 0; i < moduleDoc.declarations.length; i++) {
-					const shouldRemove = processPublicAPI(moduleDoc.declarations[i]) || ["function", "variable"].includes(moduleDoc.declarations[i].kind)
-					if (shouldRemove) {
-						moduleDoc.declarations.splice(i, 1);
-						i--;
-					}
-				}
-
 				moduleDoc.path = moduleDoc.path?.replace(/^src/, "dist").replace(/\.ts$/, ".js");
 
 				moduleDoc.exports = moduleDoc.exports.
@@ -456,41 +475,51 @@ export default {
 						})
 					}
 				})
+			},
+			packageLinkPhase({ customElementsManifest }) {
+				customElementsManifest.modules.forEach(moduleDoc => {
+					for (let i = 0; i < moduleDoc.declarations.length; i++) {
+						const shouldRemove = processPublicAPI(moduleDoc.declarations[i]) || ["function", "variable"].includes(moduleDoc.declarations[i].kind)
+						if (shouldRemove) {
+							moduleDoc.declarations.splice(i, 1);
+							i--;
+						}
+					}
 
-				const typeReferences = new Set();
-				const registerTypeReference = reference => typeReferences.add(JSON.stringify(reference))
-
-				moduleDoc.declarations.forEach(declaration => {
-					["events", "slots", "members"].forEach(memberType => {
-						declaration[memberType]?.forEach(member => {
-							if (member.type?.references) {
-								member.type.references.forEach(registerTypeReference)
-							} else if (member._ui5type?.references) {
-								member._ui5type.references.forEach(registerTypeReference)
-							} else if (member.kind === "method") {
-								member.return?.type?.references?.forEach(registerTypeReference)
-
-								member.parameters?.forEach(parameter => {
-									parameter.type?.references?.forEach(registerTypeReference)
-								})
-							}
+					const typeReferences = new Set();
+					const registerTypeReference = reference => typeReferences.add(JSON.stringify(reference))
+
+					moduleDoc.declarations.forEach(declaration => {
+						["events", "slots", "members"].forEach(memberType => {
+							declaration[memberType]?.forEach(member => {
+								if (member.type?.references) {
+									member.type.references.forEach(registerTypeReference)
+								} else if (member._ui5type?.references) {
+									member._ui5type.references.forEach(registerTypeReference)
+								} else if (member.kind === "method") {
+									member.return?.type?.references?.forEach(registerTypeReference)
+
+									member.parameters?.forEach(parameter => {
+										parameter.type?.references?.forEach(registerTypeReference)
+									})
+								}
+							})
 						})
-					})
-				});
+					});
 
-				typeReferences.forEach(reference => {
-					reference = JSON.parse(reference);
-					if (reference.package === packageJSON?.name && reference.module === moduleDoc.path) {
-						const hasExport = moduleDoc.exports.some(e => e.declaration?.name === reference.name && e.declaration?.module === reference.module)
+					typeReferences.forEach(reference => {
+						reference = JSON.parse(reference);
+						if (reference.package === packageJSON?.name && reference.module === moduleDoc.path) {
+							const hasExport = moduleDoc.exports.some(e => e.declaration?.name === reference.name && e.declaration?.module === reference.module)
 
-						if (!hasExport) {
-							logDocumentationError(moduleDoc.path?.replace(/^dist/, "src").replace(/\.js$/, ".ts"), `Type '${reference.name}' is used to describe a public API but is not exported.`,)
+							if (!hasExport) {
+								logDocumentationError(moduleDoc.path?.replace(/^dist/, "src").replace(/\.js$/, ".ts"), `Type '${reference.name}' is used to describe a public API but is not exported.`,)
+							}
 						}
-					}
-				})
-			},
-			packageLinkPhase({ context }) {
-				if (context.dev) {
+					})
+				});
+
+				if (devMode) {
 					displayDocumentationErrors();
 				}
 			}

package/lib/cem/event.mjs

@@ -16,19 +16,10 @@ import {
 } from "./utils.mjs";
 
 const jsDocRegExp = /\/\*\*(.|\n)+?\s+\*\//;
+const ASTFalseKeywordCode = 94;
 
 const getParams = (ts, eventDetails, commentParams, classNode, moduleDoc) => {
 	return commentParams?.map(commentParam => {
-		const decoratorParam = eventDetails?.find(prop => prop?.name?.text === commentParam?.name);
-
-		if (!decoratorParam || !decoratorParam?.jsDoc?.[0]) {
-			return;
-		}
-
-		const decoratorParamParsedComment = parse(decoratorParam?.jsDoc?.[0]?.getText?.(), { spacing: 'preserve' })[0];
-
-		validateJSDocComment("eventParam", decoratorParamParsedComment, decoratorParam.name?.text, moduleDoc);
-
 		const { typeName, name } = getType(normalizeTagType(commentParam?.type));
 		let type;
 
@@ -47,12 +38,10 @@ const getParams = (ts, eventDetails, commentParams, classNode, moduleDoc) => {
 		return {
 			type,
 			name: commentParam?.name,
-			_ui5privacy: getPrivacyStatus(decoratorParamParsedComment),
+			_ui5privacy: "public",
 			description: normalizeDescription(commentParam?.description),
-			_ui5since: getSinceStatus(decoratorParamParsedComment),
-			deprecated: getDeprecatedStatus(decoratorParamParsedComment),
 		};
-	}).filter(pair => !!pair);
+	});
 };
 
 function processEvent(ts, event, classNode, moduleDoc) {
@@ -77,30 +66,32 @@ function processEvent(ts, event, classNode, moduleDoc) {
 	const privacy = findTag(eventParsedComment, ["public", "private", "protected"])?.tag || "private";
 	const sinceTag = findTag(eventParsedComment, "since");
 	const commentParams = findAllTags(eventParsedComment, "param");
-	const allowPreventDefault = hasTag(eventParsedComment, "allowPreventDefault") || undefined;
 	const description = normalizeDescription(eventParsedComment?.description);
 	const native = hasTag(eventParsedComment, "native");
-	const eventDetails = event?.expression?.arguments?.[1]?.properties?.find(prop => prop?.name?.text === "detail")?.initializer?.properties;
-
-	if (event?.expression?.arguments?.[1] && !event?.expression?.typeArguments) {
-		logDocumentationError(moduleDoc.path, `Event details for event '${name}' must be described using generics. Add type via generics to the decorator: @event<TypeForDetails>("${name}", {details}).`)
-	}
+	const eventArgs = event?.expression?.arguments;
+	let eventBubbles;
+	let eventCancelable;
+	let eventDetails;
+
+	eventArgs && eventArgs.forEach(arg => {
+		arg.properties?.forEach(prop => {
+			if (prop.name?.text === "bubbles") {
+				eventBubbles = prop.initializer.kind === ASTFalseKeywordCode ? false : true;
+			} else if (prop.name?.text === "cancelable") {
+				eventCancelable = prop.initializer.kind === ASTFalseKeywordCode ? false : true;
+			} else if (prop.name?.text === "detail") {
+				eventDetails = prop.initializer?.properties;
+			}
+		});
+	});
 
 	result.description = description;
-	result._ui5allowPreventDefault = allowPreventDefault;
+	result._ui5Cancelable = eventCancelable !== undefined ? eventCancelable : false;
+	result._ui5allowPreventDefault = result._ui5Cancelable;
+	result._ui5Bubbles = eventBubbles !== undefined ? eventBubbles : false;
 
 	if (native) {
 		result.type = { text: "Event" };
-	} else if (event?.expression?.typeArguments) {
-		const typesText = event?.expression?.typeArguments.map(type => type.typeName?.text).filter(Boolean).join(" | ");
-		const typeRefs = (getTypeRefs(ts, event.expression)
-			?.map(e => getReference(ts, e, event, moduleDoc.path)).filter(Boolean)) || [];
-
-		result.type = { text: `CustomEvent<${typesText}>` };
-
-		if (typeRefs.length) {
-			result.type.references = typeRefs;
-		}
 	}
 
 	if (privacy) {
@@ -121,7 +112,53 @@ function processEvent(ts, event, classNode, moduleDoc) {
 			: sinceTag.name;
 	}
 
-	if (commentParams && eventDetails) {
+	const eventDetailType = classNode.members?.find(member => {
+		return ts.isPropertyDeclaration(member) && member.name.text === "eventDetails"
+	})?.type;
+	const eventDetailRef = eventDetailType?.members?.find(member => member.name.text === name) || eventDetailType?.types?.[eventDetailType?.types?.length - 1]?.members?.find(member => member.name.text === name);
+	const hasGeneric = !!event?.expression?.typeArguments
+
+	if (commentParams.length) {
+		if (eventDetailRef && hasGeneric) {
+			logDocumentationError(moduleDoc.path, `Event details for event '${name}' has to be defined either with generic or with eventDetails.`)
+		} else if (eventDetails) {
+			if (hasGeneric) {
+				const typesText = event?.expression?.typeArguments.map(type => type.typeName?.text).filter(Boolean).join(" | ");
+				const typeRefs = (getTypeRefs(ts, event.expression)
+					?.map(e => getReference(ts, e, event, moduleDoc.path)).filter(Boolean)) || [];
+
+				result.type = { text: `CustomEvent<${typesText}>` };
+
+				if (typeRefs.length) {
+					result.type.references = typeRefs;
+				}
+			} else if (eventDetailRef) {
+				const typesText = eventDetailRef?.type?.typeName?.text;
+				const typeRefs = (getTypeRefs(ts, eventDetailRef)
+					?.map(e => getReference(ts, e, event, moduleDoc.path)).filter(Boolean)) || [];
+
+				result.type = { text: `CustomEvent<${typesText}>` };
+
+				if (typeRefs.length) {
+					result.type.references = typeRefs;
+				}
+			} else {
+				logDocumentationError(moduleDoc.path, `Event details for event '${name}' must be described using generics. Add type via generics to the decorator: @event<TypeForDetails>("${name}", {details}).`)
+			}
+		} else if (eventDetailRef) {
+			const typesText = eventDetailRef?.type?.typeName?.text;
+			const typeRefs = (getTypeRefs(ts, eventDetailRef)
+				?.map(e => getReference(ts, e, event, moduleDoc.path)).filter(Boolean)) || [];
+
+			result.type = { text: `CustomEvent<${typesText}>` };
+
+			if (typeRefs.length) {
+				result.type.references = typeRefs;
+			}
+		} else {
+			logDocumentationError(moduleDoc.path, `Event details for event '${name}' must be described.`)
+		}
+
 		result._ui5parameters = getParams(ts, eventDetails, commentParams, classNode, moduleDoc);
 	}
 

package/lib/cem/schema-internal.json

@@ -46,6 +46,12 @@
     "ClassDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -123,6 +129,12 @@
     "EnumDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -187,6 +199,12 @@
     "InterfaceDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -389,6 +407,9 @@
     "CssCustomProperty": {
       "additionalProperties": false,
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "default": {
           "type": "string"
         },
@@ -425,6 +446,9 @@
       "additionalProperties": false,
       "description": "The description of a CSS Part",
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "deprecated": {
           "description": "Whether the CSS shadow part is deprecated.\nIf the value is a string, it's the reason for the deprecation.",
           "type": [
@@ -453,6 +477,12 @@
       "additionalProperties": false,
       "description": "A description of a custom element class.\n\nCustom elements are JavaScript classes, so this extends from\n`ClassDeclaration` and adds custom-element-specific features like\nattributes, events, and slots.\n\nNote that `tagName` in this interface is optional. Tag names are not\nneccessarily part of a custom element class, but belong to the definition\n(often called the \"registration\") or the `customElements.define()` call.\n\nBecause classes and tag names can only be registered once, there's a\none-to-one relationship between classes and tag names. For ease of use,\nwe allow the tag name here.\n\nSome packages define and register custom elements in separate modules. In\nthese cases one `Module` should contain the `CustomElement` without a\ntagName, and another `Module` should contain the\n`CustomElementExport`.",
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -618,6 +648,12 @@
       "additionalProperties": false,
       "description": "A class mixin that also adds custom element related properties.",
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -788,6 +824,14 @@
           "description": "Whether the parameter is optional. Undefined implies non-optional.",
           "type": "boolean"
         },
+        "_ui5Cancelable": {
+          "description": "Whether the event is cancelable or not.",
+          "type": "boolean"
+        },
+        "_ui5Bubbles": {
+          "description": "Whether the event bubbles or not.",
+          "type": "boolean"
+        },
         "_ui5since": {
           "description": "Marks when the field was introduced",
           "type": "string"
@@ -827,6 +871,12 @@
     "FunctionDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -1007,6 +1057,12 @@
       "additionalProperties": false,
       "description": "A description of a class mixin.\n\nMixins are functions which generate a new subclass of a given superclass.\nThis interfaces describes the class and custom element features that\nare added by the mixin. As such, it extends the CustomElement interface and\nClassLike interface.\n\nSince mixins are functions, it also extends the FunctionLike interface. This\nmeans a mixin is callable, and has parameters and a return type.\n\nThe return type is often hard or impossible to accurately describe in type\nsystems like TypeScript. It requires generics and an `extends` operator\nthat TypeScript lacks. Therefore it's recommended that the return type is\nleft empty. The most common form of a mixin function takes a single\nargument, so consumers of this interface should assume that the return type\nis the single argument subclassed by this declaration.\n\nA mixin should not have a superclass. If a mixins composes other mixins,\nthey should be listed in the `mixins` field.\n\nSee [this article]{@link https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/}\nfor more information on the classmixin pattern in JavaScript.",
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },
@@ -1172,6 +1228,9 @@
     "Slot": {
       "additionalProperties": false,
       "properties": {
+        "inheritedFrom": {
+          "$ref": "#/definitions/Reference"
+        },
         "_ui5propertyName": {
           "type": "string"
         },
@@ -1275,6 +1334,12 @@
     "VariableDeclaration": {
       "additionalProperties": false,
       "properties": {
+        "_ui5experimental": {
+          "type": [
+            "string",
+            "boolean"
+          ]
+        },
         "_ui5package": {
           "type": "string"
         },

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

@@ -319,9 +319,20 @@ export interface Event {
   _ui5parameters?: Parameter[]
   _ui5privacy?: Privacy
   /**
-   * Whether the parameter is optional. Undefined implies non-optional.
+   * Whether the event is preventable.
+   */
+  _ui5allowPreventDefault?: boolean;
+
+  /**
+   * Whether the event is cancelable.
    */
-  _ui5allowPreventDefault?: boolean
+  _ui5Cancelable?: boolean;
+
+  /**
+   * Whether the event is bubbles.
+   */
+  _ui5Bubbles?: boolean;
+
   /**
    * Marks when the field was introduced
    */
@@ -484,6 +495,7 @@ export interface TypeReference extends Reference {
  * The common interface of classes and mixins.
  */
 export interface ClassLike {
+  _ui5experimental?: boolean | string
   _ui5implements?: Reference[]
   _ui5privacy?: Privacy
   /**