@ui5/webcomponents-tools 0.0.0-b132dd7b9 → 0.0.0-b3a4f8020

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/utils/manifest-helpers.js

@@ -0,0 +1,194 @@
+/**
+ * UTILITIES RELATED TO GETTING INFORMATION OUT OF A MANIFEST OR DOC
+ */
+
+import { has } from "./index.js";
+
+/**
+ * @typedef {import('custom-elements-manifest/schema').Package} Package
+ */
+
+function loopThroughDeclarations(manifest, predicate) {
+  manifest?.modules?.forEach(_module => {
+    _module?.declarations?.forEach(predicate);
+  });
+}
+
+function loopThroughExports(manifest, predicate) {
+  manifest?.modules?.forEach(_module => {
+    _module?.exports?.forEach(predicate);
+  });
+}
+
+/**
+ * Loops through all modules' exports, and returns the kind provided by the users
+ *
+ * @example getKind('class');
+ * @example getKind('custom-element-definition');
+ */
+export function getAllExportsOfKind(manifest, kind) {
+  const result = [];
+  loopThroughExports(manifest, (_export) => {
+    if(_export.kind === kind) {
+      result.push(_export);
+    }
+  });
+  return result;
+}
+
+
+/**
+ * Loops through all modules' declarations, and returns the kind provided by the users
+ *
+ * @example getKind('class');
+ * @example getKind('custom-element-definition');
+ */
+export function getAllDeclarationsOfKind(manifest, kind) {
+  const result = [];
+  loopThroughDeclarations(manifest, (declaration) => {
+    if(declaration.kind === kind) {
+      result.push(declaration);
+    }
+  });
+  return result;
+}
+
+/**
+ * Gets the inheritance tree from a manifest given a className
+ * Returns an array of a classes mixins/superclasses all the way up the chain
+ *
+ * @param {Package[]} manifests
+ * @param {string} className
+ */
+export function getInheritanceTree(manifests, className) {
+  const tree = [];
+  const allClassLikes = new Map();
+  const _classes = [];
+  const _mixins = [];
+
+  manifests.forEach((cem) => {
+    _classes.push(...getAllDeclarationsOfKind(cem, 'class'));
+    _mixins.push(...getAllDeclarationsOfKind(cem, 'mixin'));
+  });
+
+  [..._mixins, ..._classes].forEach((klass) => {
+    allClassLikes.set(klass.name, klass);
+  });
+
+  let klass = allClassLikes.get(className)
+
+  if(klass) {
+    tree.push(klass)
+
+    klass?.mixins?.forEach(mixin => {
+      let foundMixin = _mixins.find(m => m.name === mixin.name);
+      if(foundMixin) {
+        tree.push(foundMixin);
+
+        while(has(foundMixin?.mixins)) {
+          foundMixin?.mixins?.forEach(mixin => {
+            foundMixin =  _mixins.find(m => m.name === mixin.name);
+            if(foundMixin) {
+              tree.push(foundMixin);
+            }
+          });
+        }
+      }
+    });
+
+    while(allClassLikes.has(klass.superclass?.name)) {
+      const newKlass = allClassLikes.get(klass.superclass.name);
+      let allMixins = [];
+      if (klass?.mixins) {
+        allMixins = [...klass.mixins];
+      }
+      if (newKlass?.mixins) {
+        allMixins = [...allMixins, ...newKlass.mixins];
+      }
+
+      allMixins.forEach(mixin => {
+        let foundMixin = _mixins.find(m => m.name === mixin.name);
+        if(foundMixin) {
+          tree.push(foundMixin);
+
+          while(has(foundMixin?.mixins)) {
+            foundMixin?.mixins?.forEach(mixin => {
+              foundMixin =  _mixins.find(m => m.name === mixin.name);
+              if(foundMixin) {
+                tree.push(foundMixin);
+              }
+            });
+          }
+        }
+      });
+
+      tree.push(newKlass);
+      klass = newKlass;
+    }
+    return tree;
+  }
+  return [];
+}
+
+/**
+ * @param {Package[]} manifests
+ * @param {string} modulePath
+ */
+ export function getModuleFromManifests(manifests, modulePath) {
+   let result = undefined;
+
+   manifests.forEach((cem) => {
+    cem?.modules?.forEach((_module) => {
+      if (_module.path === modulePath) {
+        result = _module;
+      }
+    });
+  });
+
+  return result;
+}
+
+/**
+ * @param {Package[]} manifests
+ * @param {string} className
+ */
+ export function getModuleForClassLike(manifests, className) {
+  let result = undefined;
+
+  manifests.forEach((cem) => {
+    cem?.modules?.forEach(_module => {
+      _module?.declarations?.forEach(declaration => {
+        if((declaration.kind === 'class' || declaration.kind === 'mixin') && declaration.name === className) {
+          result = _module.path;
+        }
+      });
+    });
+  });
+
+  return result;
+}
+
+/**
+ * Given a manifest module, a class name, and a class member name, gets the
+ * manifest doc for the module's class' member.
+ *
+ * @param  {Partial<import('custom-elements-manifest/schema').Module>} moduleDoc Manifest module
+ * @param  {string} className Class to get member of
+ * @param  {string} memberName Class member to get
+ * @param  {boolean} isStatic Is it a static member?
+ * @return {import('custom-elements-manifest/schema').ClassMember|void} the requested class member
+ */
+export function getClassMemberDoc(moduleDoc, className, memberName, isStatic = false) {
+  /** @type {import('custom-elements-manifest/schema').ClassDeclaration} */
+  const classDoc = (moduleDoc.declarations.find(x => x.name === className));
+
+  if (!classDoc || !has(classDoc.members))
+    return;
+
+  const memberDoc = classDoc.members.find(x =>
+    x.name === memberName &&
+    (x.static ?? false) === isStatic
+  );
+
+  return memberDoc;
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/utils/mixins.js

@@ -0,0 +1,112 @@
+import ts from 'typescript';
+
+import { getReturnValue } from '../utils/ast-helpers.js';
+
+export const isMixin = node => !!extractMixinNodes(node);
+
+export function extractMixinNodes(node) {
+  if (ts.isVariableStatement(node) || ts.isFunctionDeclaration(node)) {
+    if (ts.isVariableStatement(node)) {
+      /**
+       * @example const MyMixin = klass => class MyMixin extends klass {}
+       * @example export const MyMixin = klass => class MyMixin extends klass {}
+       */
+      const variableDeclaration = node.declarationList.declarations.find(declaration =>
+        ts.isVariableDeclaration(declaration),
+      );
+      if (variableDeclaration) {
+        const body = variableDeclaration?.initializer?.body;
+        if (body && ts.isClassExpression(body)) {
+          return { 
+            mixinFunction: node,
+            mixinClass: body,
+          };
+        }
+
+        /**
+         * @example const MyMixin = klass => { return class MyMixin extends Klass{} }
+         */
+        if (body && ts.isBlock(body)) {
+          const returnStatement = body.statements.find(statement => ts.isReturnStatement(statement));
+
+          if (returnStatement && returnStatement?.expression?.kind && ts.isClassExpression(returnStatement.expression)) {
+            return { 
+              mixinFunction: variableDeclaration.initializer,
+              mixinClass: returnStatement.expression
+            };
+          }
+        }
+
+        /**
+         * @example const MyMixin = klass => { class MyMixin extends klass {} return MyMixin;}
+         */
+        if (body && ts.isBlock(body)) {
+          const classDeclaration = body.statements.find(statement => ts.isClassDeclaration(statement));
+          const returnStatement = body.statements.find(statement => ts.isReturnStatement(statement));
+          /** Avoid undefined === undefined */
+          if(!(classDeclaration && returnStatement))
+            return;
+          const classDeclarationName = classDeclaration.name?.getText?.();
+          const returnValue = getReturnValue(returnStatement)
+          /**
+           * If the classDeclaration inside the function body has the same name as whats being
+           * returned from the function, consider it a mixin
+           */
+          if (classDeclarationName === returnValue) {
+            return {
+              mixinFunction: node,
+              mixinClass: classDeclaration
+            }
+          }
+        }
+      }
+    }
+
+    /**
+     *  @example function MyMixin(klass) { return class MyMixin extends Klass{} }
+     */
+    if (ts.isFunctionDeclaration(node)) {
+      if (node.body && ts.isBlock(node.body)) {
+
+        const returnStatement = node.body.statements.find(statement => ts.isReturnStatement(statement));
+
+        if (returnStatement?.expression && ts.isClassExpression(returnStatement.expression)) {
+          return { 
+            mixinFunction: node, 
+            mixinClass: returnStatement.expression
+          };
+        }
+      }
+    }
+
+    /**
+     * @example function MyMixin(klass) {class A extends klass {} return A;}
+     */
+    if (ts.isFunctionDeclaration(node)) {
+      if (node.body && ts.isBlock(node.body)) {
+        const classDeclaration = node.body.statements.find(statement => ts.isClassDeclaration(statement));
+        const returnStatement = node.body.statements.find(statement => ts.isReturnStatement(statement));
+
+        /** Avoid undefined === undefined */
+        if(!(classDeclaration && returnStatement))
+          return;
+
+        const classDeclarationName = classDeclaration.name?.getText?.();
+
+        const returnValue = getReturnValue(returnStatement)
+
+        /**
+         * If the classDeclaration inside the function body has the same name as whats being
+         * returned from the function, consider it a mixin
+         */
+        if (classDeclarationName === returnValue) {
+          return {
+            mixinFunction: node,
+            mixinClass: classDeclaration
+          }
+        }
+      }
+    }
+  }
+  return false;
+}

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,