@zywave/customelement-manifest-element 1.0.2 → 1.2.0

package/README.md

@@ -0,0 +1,23 @@
+@zywave/customelement-manifest-element
+
+The `<customelement-manifest-element>` custom element is built to render a standards-compliant [custom element manifest](https://github.com/webcomponents/custom-elements-manifest/) in a user friendly way. This element is used in https://zui.zywave.com to render our own web component documentation.
+
+## Example
+
+```html
+<customelement-manifest-element src="./custom-elements.json"></customelement-manifest-element>
+```
+
+## API
+Read the [api docs](./docs/api.md) for more information.
+
+## Experimental
+
+This component uses some experimental features that are only in the latest versions of Chrome or Firefox.
+
+To use this in other browsers that support native ES modules, you can use [es-module-shims](https://github.com/guybedford/es-module-shims).
+
+We use:
+
+- [import assertions](https://github.com/tc39/proposal-import-assertions) to load CSS
+- [CSS Houdini Properties and Values API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Properties_and_Values_API)

package/customelement-manifest-element.css

@@ -21,7 +21,7 @@
 }
 
 section + section {
-  margin-top: 40px;
+  margin-top: 2.5rem;
 }
 
 h1 {
@@ -48,7 +48,7 @@ table span {
 }
 table thead th,
 table tbody td {
-  padding: 15px;
+  padding: 0.9375rem;
 }
 table thead th:first-child,
 table tbody td:first-child {
@@ -68,7 +68,8 @@ table tbody tr:last-child > td {
   border-bottom: 0;
 }
 table tbody td {
-  padding: 15px;
+  vertical-align: top;
+  padding: 0.9375rem;
   border-bottom: 1px solid hsla(var(--schema-primary-color-h), var(--schema-primary-color-s), var(--schema-primary-color-l), 0.1);
 }
 table tbody td:first-child {
@@ -81,13 +82,25 @@ table tbody td.name, table tbody td.type, table tbody td.default {
   width: 16.667%;
 }
 table tbody td.name span, table tbody td.type span, table tbody td.default span {
-  padding: 5px 10px;
+  padding: 0.3125rem 0.625rem;
 }
-table tbody td.name span, table tbody td.type span {
+table tbody td.name span, table tbody td.type span, table tbody td.signature span {
   font-family: monospace;
   background-color: hsla(var(--schema-primary-color-h), var(--schema-primary-color-s), var(--schema-primary-color-l), 0.1);
   color: var(--schema-primary-color);
 }
+table tbody td.signature span {
+  padding: 0.3125rem 0.625rem;
+}
+table tbody td.signature .expanded-details {
+  margin-left: 1.5625rem;
+}
+table tbody td.signature .param-container {
+  margin-top: 0.3125rem;
+}
+table tbody td.signature .param-description {
+  margin-left: 0.9375rem;
+}
 table tbody td.summary {
   width: 50%;
 }
@@ -111,7 +124,7 @@ a:hover {
 }
 a:focus {
   outline: 1px solid var(--schema-accent-color);
-  outline-offset: 4px;
+  outline-offset: 0.25rem;
   text-decoration: none;
 }
 a:active {
@@ -126,11 +139,11 @@ code {
 
 select {
   display: inline-block;
-  height: 36px;
+  height: 2.25rem;
   padding: 0 1em;
-  padding-right: 35px;
+  padding-right: 2.1875rem;
   border: 1px solid #cbcbd2;
-  border-radius: 4px;
+  border-radius: 0.25rem;
   outline: none;
   font: inherit;
   cursor: pointer;

package/customelement-manifest-element.d.ts

@@ -33,7 +33,7 @@ export declare class CustomElementManifestElement extends LitElement {
      */
     get initialHeaderLevel(): 1 | 2 | 3;
     set initialHeaderLevel(value: 1 | 2 | 3);
-    static get styles(): any[];
+    static get styles(): CSSStyleSheet[];
     constructor();
     firstUpdated(changedProps: PropertyValues): void;
     update(changedProps: PropertyValues): void;

package/customelement-manifest-element.js

@@ -3,9 +3,9 @@ import { __decorate } from "tslib";
 /* eslint-disable lit/binding-positions */
 import { LitElement, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
-// @ts-ignore
-import css from "./customelement-manifest-element.css" assert { type: 'css' };
+import css from "./customelement-manifest-element.css" assert { type: 'css' }; // eslint-disable-line
 import { html, unsafeStatic } from "lit/static-html.js";
+import { findDefinition, getElementNames } from "./manifest-helpers";
 function publicMembersFilter(classMember) {
     return ((!classMember.privacy || classMember.privacy === "public") &&
         !classMember.name.startsWith("_") &&
@@ -33,7 +33,7 @@ function buildTable(items, columns) {
     <tbody> ${rows} </tbody>
   </table>`;
 }
-function renderDescripton(str) {
+function renderDescription(str) {
     if (!str) {
         return str;
     }
@@ -47,6 +47,37 @@ function renderDescripton(str) {
     }
     return result;
 }
+function renderMethodSignature(obj) {
+    const methodReturn = () => {
+        const returnType = obj.return?.type?.text;
+        if (returnType?.length === 0) {
+            return 'void';
+        }
+        return returnType ?? 'unknown';
+    };
+    if (obj.parameters) {
+        const methodSignatureSummary = obj.parameters?.map(param => param.name + (param.optional ? '?' : '')).join(', ');
+        const methodParametersDetailed = obj.parameters?.map(param => {
+            const argumentType = `: ${param?.type?.text}${param.default ? ` = ${param.default}` : ''}`;
+            const argumentHtml = param.name + (param.optional ? '?' : '') + argumentType;
+            return html `
+        <div class="param-container">
+          <div class="param">${argumentHtml}</div>
+          ${param.description
+                ? html `<div class="param-description">${renderDescription(param.description)}</div>`
+                : nothing}
+        </div>
+      `;
+        });
+        return html `<details>
+      <summary>${obj.name}(${methodSignatureSummary}): ${methodReturn()}</summary>
+      <div class="expanded-details">${methodParametersDetailed}</div>
+    </details>`;
+    }
+    else {
+        return html `${obj.name}(): ${methodReturn()}`;
+    }
+}
 function prettify(str) {
     let regexMatch;
     const linkRegex = /^https?:\/\//;
@@ -114,34 +145,25 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
     #failedLoad;
     // eslint-disable-next-line no-undef
     #internals;
-    get #customElementDefinitions() {
-        if (this.#schema) {
-            const customElementExports = (this.#schema.modules
-                .flatMap((x) => x.exports)
-                .filter((x) => x?.kind === "custom-element-definition") ?? []);
-            const arr = [];
-            for (const ce of customElementExports) {
-                if (this.elementNames && !this.elementNames.includes(ce.name)) {
-                    continue;
-                }
-                const containingModule = this.#schema.modules.find((x) => x.path === ce.declaration.module);
-                if (containingModule) {
-                    const classDef = containingModule.declarations?.find((x) => x.kind === "class");
-                    if (classDef) {
-                        arr.push({
-                            name: ce.name,
-                            declaration: classDef,
-                        });
-                    }
-                }
-            }
-            return arr.sort((a, b) => a.name.localeCompare(b.name));
+    get #elementNames() {
+        if (!this.#schema) {
+            return [];
         }
-        return [];
+        let elementNames = getElementNames(this.#schema);
+        if (this.elementNames) {
+            elementNames = elementNames.filter((x) => this.elementNames.includes(x));
+        }
+        return elementNames.sort((a, b) => a.localeCompare(b));
     }
     get #activeElement() {
-        return (this.#customElementDefinitions.find((x) => x.name === this.#activeElementName) ??
-            this.#customElementDefinitions[0]);
+        if (!this.#schema) {
+            return undefined;
+        }
+        this.#activeElementName ??= this.#elementNames[0];
+        if (!this.#activeElementName) {
+            return undefined;
+        }
+        return findDefinition(this.#schema, this.#activeElementName);
     }
     constructor() {
         super();
@@ -170,20 +192,20 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         }
         return this.#activeElement
             ? html `<article>
-            <div class="header-row"><${getHeaderTag(this.initialHeaderLevel)}>${this.#activeElement.name}</${getHeaderTag(this.initialHeaderLevel)}>${this.#renderElementChooser()}</div>
-            <div>${renderDescripton(this.#activeElement.declaration.description)}</div>
+            <div class="header-row"><${getHeaderTag(this.initialHeaderLevel)}>${this.#activeElementName}</${getHeaderTag(this.initialHeaderLevel)}>${this.#renderElementChooser()}</div>
+            <div>${renderDescription(this.#activeElement.description)}</div>
             ${this.#renderAttributes()} ${this.#renderProperties()} ${this.#renderCssProperties()}
             ${this.#renderCssShadowParts()} ${this.#renderEvents()} ${this.#renderMethods()} ${this.#renderSlots()} </article
           >`
             : nothing;
     }
     #renderElementChooser() {
-        if (this.#customElementDefinitions.length > 1) {
-            let selectedElement = this.#customElementDefinitions.find((x) => x.name === this.#activeElementName)?.name;
+        if (this.#elementNames.length > 1) {
+            let selectedElement = this.#elementNames.find((x) => x === this.#activeElementName);
             if (!selectedElement) {
-                selectedElement = this.#customElementDefinitions[0]?.name;
+                selectedElement = this.#elementNames[0];
             }
-            const options = this.#customElementDefinitions.map((x) => html `<option ?selected="${x.name === selectedElement}" value="${x.name}">${x.name}</option>`);
+            const options = this.#elementNames.map((x) => html `<option ?selected="${x === selectedElement}" value="${x}">${x}</option>`);
             return html `<select part="chooser" @change="${this.#onElementChange}"
         >${options}</select
       >`;
@@ -191,7 +213,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         return nothing;
     }
     #renderAttributes() {
-        const attributes = this.#activeElement?.declaration.attributes;
+        const attributes = this.#activeElement?.attributes;
         if (attributes?.length) {
             const table = buildTable(attributes, [
                 {
@@ -205,7 +227,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
                     header: "Description",
                     type: "summary",
                     valueAccessor(item) {
-                        return renderDescripton(item.description);
+                        return renderDescription(item.description);
                     },
                 },
                 {
@@ -235,7 +257,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         }
     }
     #renderProperties() {
-        const props = this.#activeElement?.declaration.members?.filter((x) => x.kind === "field" && publicMembersFilter(x));
+        const props = this.#activeElement?.members?.filter((x) => x.kind === "field" && publicMembersFilter(x));
         if (props?.length) {
             const table = buildTable(props, [
                 {
@@ -248,7 +270,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
                 {
                     header: "Description",
                     valueAccessor(item) {
-                        return renderDescripton(item.description);
+                        return renderDescription(item.description);
                     },
                     type: "summary",
                 },
@@ -277,7 +299,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         return nothing;
     }
     #renderCssProperties() {
-        const cssProps = this.#activeElement?.declaration.cssProperties;
+        const cssProps = this.#activeElement?.cssProperties;
         if (cssProps?.length) {
             const table = buildTable(cssProps, [
                 {
@@ -290,7 +312,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
                 {
                     header: "Description",
                     valueAccessor(item) {
-                        return renderDescripton(item.description);
+                        return renderDescription(item.description);
                     },
                     type: "summary",
                 },
@@ -312,7 +334,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         return nothing;
     }
     #renderCssShadowParts() {
-        const cssParts = this.#activeElement?.declaration.cssParts;
+        const cssParts = this.#activeElement?.cssParts;
         if (cssParts?.length) {
             const table = buildTable(cssParts, [
                 {
@@ -325,7 +347,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
                 {
                     header: "Description",
                     valueAccessor(item) {
-                        return renderDescripton(item.description);
+                        return renderDescription(item.description);
                     },
                     type: "summary",
                 },
@@ -340,7 +362,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         return nothing;
     }
     #renderEvents() {
-        const events = this.#activeElement?.declaration.events;
+        const events = this.#activeElement?.events;
         if (events?.length) {
             const table = buildTable(events, [
                 {
@@ -353,14 +375,14 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
                 {
                     header: "Description",
                     valueAccessor(item) {
-                        return renderDescripton(item.description);
+                        return renderDescription(item.description);
                     },
                     type: "summary",
                 },
                 {
                     header: "Type",
                     valueAccessor(item) {
-                        return item.type.text;
+                        return item.type?.text;
                     },
                     type: "type",
                 },
@@ -375,7 +397,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         return nothing;
     }
     #renderMethods() {
-        const methods = this.#activeElement?.declaration.members?.filter((x) => x.kind === "method" && publicMembersFilter(x));
+        const methods = this.#activeElement?.members?.filter((x) => x.kind === "method" && publicMembersFilter(x));
         if (methods?.length) {
             const table = buildTable(methods, [
                 {
@@ -388,10 +410,17 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
                 {
                     header: "Description",
                     valueAccessor(item) {
-                        return renderDescripton(item.description);
+                        return renderDescription(item.description);
                     },
                     type: "summary",
                 },
+                {
+                    header: "Signature",
+                    valueAccessor(item) {
+                        return renderMethodSignature(item);
+                    },
+                    type: "signature",
+                },
             ]);
             return html `
         <section part="methods">
@@ -403,7 +432,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
         return nothing;
     }
     #renderSlots() {
-        const slots = this.#activeElement?.declaration.slots;
+        const slots = this.#activeElement?.slots;
         if (slots?.length) {
             const table = buildTable(slots, [
                 {
@@ -420,7 +449,7 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
                 {
                     header: "Description",
                     valueAccessor(item) {
-                        return renderDescripton(item.description);
+                        return renderDescription(item.description);
                     },
                     type: "summary",
                 },
@@ -446,7 +475,12 @@ let CustomElementManifestElement = class CustomElementManifestElement extends Li
             if (response.ok) {
                 const data = await response.json();
                 this.#schema = data;
-                this.#activeElementName = this.initialElementName ?? this.#customElementDefinitions[0]?.name;
+                if (this.initialElementName && this.#elementNames.includes(this.initialElementName)) {
+                    this.#activeElementName = this.initialElementName;
+                }
+                else {
+                    this.#activeElementName = this.#elementNames[0];
+                }
                 this.requestUpdate();
             }
             else {

package/manifest-helpers.d.ts

@@ -0,0 +1,4 @@
+import type { Package, CustomElementDeclaration, CustomElement } from "custom-elements-manifest/schema";
+export declare function getElementNames(schema: Package): string[];
+export declare function findDefinition(schema: Package, tagName: string): (CustomElementDeclaration & CustomElement) | undefined;
+//# sourceMappingURL=manifest-helpers.d.ts.map

package/manifest-helpers.js

@@ -0,0 +1,20 @@
+function getElementExports(schema) {
+    return schema.modules.flatMap((x) => x.exports).filter((x) => x?.kind === "custom-element-definition");
+}
+export function getElementNames(schema) {
+    return getElementExports(schema)
+        .map((x) => x?.name)
+        .filter((x) => x);
+}
+export function findDefinition(schema, tagName) {
+    const elementExport = getElementExports(schema).find((x) => x?.name === tagName);
+    if (!elementExport) {
+        return undefined;
+    }
+    const definingModule = schema.modules.find((x) => x.path === elementExport.declaration.module);
+    if (!definingModule) {
+        return undefined;
+    }
+    const definition = definingModule.declarations?.find((x) => x.kind === "class" && x.name === elementExport.declaration.name);
+    return definition;
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@zywave/customelement-manifest-element",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "main": "index.js",
   "license": "UNLICENSED",
   "type": "module",
   "dependencies": {
-    "lit": "^2.0.0-rc.2"
+    "lit": "^2.1.0"
   },
   "publishConfig": {
     "access": "public"
@@ -13,39 +13,47 @@
   "files": [
     "*.js",
     "*.css",
-    "*.d.ts"
+    "*.d.ts",
+    "README.md",
+    "custom-elements.json"
   ],
+  "resolutions": {
+    "typescript": "4.5.0-beta"
+  },
   "devDependencies": {
-    "@custom-elements-manifest/analyzer": "^0.3.2",
+    "@custom-elements-manifest/analyzer": "^0.5.5",
+    "@custom-elements-manifest/to-markdown": "^0.0.13",
     "@esm-bundle/chai": "^4.3.4",
     "@semantic-release/gitlab": "^6.2.1",
     "@semantic-release/gitlab-config": "^8.0.0",
-    "@typescript-eslint/eslint-plugin": "^4.28.0",
-    "@typescript-eslint/parser": "^4.28.0",
-    "@web/test-runner": "^0.13.12",
-    "@web/test-runner-junit-reporter": "^0.4.4",
+    "@typescript-eslint/eslint-plugin": "^4.33.0",
+    "@typescript-eslint/parser": "^4.33.0",
+    "@web/test-runner": "^0.13.18",
+    "@web/test-runner-junit-reporter": "^0.4.7",
     "@web/test-runner-playwright": "^0.8.6",
+    "@zywave/zui-sass-scripts": "^4.0.14",
     "custom-elements-manifest": "^1.0.0",
     "es-dev-server": "^2.1.0",
-    "eslint": "^7.29.0",
+    "eslint": "^7.30.0",
     "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-lit": "^1.5.1",
-    "eslint-plugin-prettier": "^3.4.0",
-    "mocha": "^9.0.1",
-    "playwright": "^1.12.2",
-    "prettier": "^2.3.1",
-    "sass": "^1.35.1",
-    "semantic-release": "^17.4.4",
+    "eslint-plugin-lit": "^1.6.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "mocha": "^9.1.2",
+    "playwright": "^1.15.2",
+    "prettier": "^2.4.1",
+    "sass": "^1.42.1",
+    "semantic-release": "^18.0.0",
     "sinon": "^11.1.1",
-    "typescript": "^4.3.4"
+    "typescript": "^4.5.0-beta"
   },
   "scripts": {
     "analyze": "cem analyze --globs \"src/customelement-manifest-element.ts\" --litelement",
-    "build": "yarn run build:ts && yarn run build:scss",
-    "build:ts": "tsc -p tsconfig.json && node scripts/assertion-postprocessor.js",
+    "build": "yarn run build:scss && yarn run build:ts",
+    "build:ts": "tsc -p tsconfig.json",
     "build:scss": "sass src/customelement-manifest-element.scss customelement-manifest-element.css",
     "clean": "git clean -dfX",
     "demo": "es-dev-server --app-index demo/index.html --node-resolve --watch --open",
+    "docs": "yarn run analyze && node scripts/docs.js",
     "lint": "eslint \"{src,test}/**/*.ts\"",
     "test": "yarn run test:build && yarn run test:run",
     "test:build": "tsc --build tsconfig.test.json && cd test/schemas && cem analyze --globs \"element.js\" && cd ../..",