@salesforcedevs/docs-components 0.49.1 → 0.54.0-alpha01

package/src/modules/doc/amfTopic/amfTopic.ts

@@ -0,0 +1,94 @@
+import { LightningElement, api } from "lwc";
+import {
+    createDocumentationElement,
+    createEndpointElement,
+    createMethodElement,
+    createSecurityElement,
+    createSummaryElement,
+    createTypeElement
+} from "./utils";
+import type { TopicModel } from "./types";
+
+export default class AmfTopic extends LightningElement {
+    private _model;
+    private amf;
+    private type;
+
+    @api
+    get model(): TopicModel {
+        return this._model;
+    }
+
+    set model(value: TopicModel) {
+        if (
+            !this.amf ||
+            (value && this._model && value.amf !== this._model?.amf)
+        ) {
+            this.amf = value && clone(value.amf);
+        }
+        if (
+            !this.type ||
+            (value && this._model && value.type !== this._model?.type)
+        ) {
+            this.type = value && clone(value.type);
+        }
+
+        this._model = value;
+        if (this._model) {
+            this.update();
+        }
+        // else { Remove child? No model, seems like no component should be shown. }
+    }
+
+    update(): void {
+        const container = this.template.querySelector("div.topic-container");
+        const { id } = this.model;
+        const type = this.type;
+        const amf = this.amf;
+        const { parser } = this.model;
+        let element;
+
+        if (type === "summary") {
+            element = createSummaryElement(amf);
+        } else if (type === "endpoint") {
+            const endpointModel = parser.computeEndpointApiModel(amf, id);
+            element = createEndpointElement(amf, endpointModel, id);
+        } else if (type === "method") {
+            const endpointMethodModel = parser.computeEndpointApiMethodModel(
+                amf,
+                id
+            );
+            const methodModel = parser.computeMethodApiModel(amf, id);
+            element = createMethodElement(
+                amf,
+                endpointMethodModel,
+                methodModel
+            );
+        } else if (type === "security") {
+            const securityModel = parser.computeSecurityApiModel(amf, id);
+            element = createSecurityElement(amf, securityModel);
+        } else if (type === "type") {
+            const mediaTypes = parser.computeApiMediaTypes(amf);
+            const typeModel = parser.computeTypeApiModel(amf, id);
+            element = createTypeElement(amf, typeModel, mediaTypes);
+        } else if (type === "documentation") {
+            const docsModel = parser.computeDocsApiModel(amf, id);
+            element = createDocumentationElement(amf, docsModel);
+        }
+
+        if (container.firstChild) {
+            container.firstChild.remove();
+        }
+        container.appendChild(element);
+    }
+}
+
+/**
+ * The underlying web components we use from api-console mutate their models we pass in.
+ * Since LWC makes them Read Only, we need to copy them before passing to the Web Component.
+ * @param value JSON Serializable object to clone.
+ * @returns A copy of Value. One that has been serialized and parsed via JSON. (Functions, Regex, etc are not preserved.)
+ */
+function clone(value): object {
+    return JSON.parse(JSON.stringify(value));
+}

package/src/modules/doc/amfTopic/types.ts

@@ -0,0 +1,54 @@
+import { Json } from "@lwrjs/types";
+
+export type ApiSummaryElement = HTMLElement & {
+    amf: Json;
+    hideToc: boolean;
+    titleLevel: string;
+};
+
+export type ApiEndpointElement = HTMLElement & {
+    amf: Json;
+    inlineMethods: boolean;
+    noNavigation: boolean;
+    selected: string;
+    endpoint: Json;
+    noTryIt: boolean;
+};
+
+export type ApiMethodElement = HTMLElement & {
+    amf: Json;
+    noNavigation: boolean;
+    endpoint: Json;
+    method: Json;
+    noTryIt: boolean;
+};
+
+export type ApiSecurityElement = HTMLElement & {
+    amf: Json;
+    security: Json;
+};
+
+export type ApiTypeElement = HTMLElement & {
+    amf: Json;
+    type: Json;
+    mediaTypes: Json;
+};
+
+export type ApiDocElement = HTMLElement & {
+    amf: Json;
+    shape: Json;
+};
+
+export type AmfModel = Json;
+
+export interface AmfParser {
+    parse(): void;
+    parsedModel: any;
+}
+
+export interface TopicModel {
+    id: string;
+    type: string;
+    amf: AmfModel;
+    parser: AmfParser;
+}

package/src/modules/doc/amfTopic/utils.ts

@@ -0,0 +1,117 @@
+import type {
+    ApiDocElement,
+    ApiEndpointElement,
+    ApiMethodElement,
+    ApiSecurityElement,
+    ApiSummaryElement,
+    ApiTypeElement
+} from "./types";
+
+import { Json } from "@lwrjs/types";
+
+export function createSummaryElement(amf: Json): HTMLElement {
+    const summaryElement: ApiSummaryElement = document.createElement(
+        "api-summary"
+    ) as ApiSummaryElement;
+    summaryElement.amf = amf;
+    summaryElement.hideToc = true;
+    summaryElement.titleLevel = "1";
+    summaryElement.setAttribute(
+        "exportparts",
+        [
+            "api-title",
+            "api-title-label",
+            "api-version",
+            "marked-description",
+            "info-section",
+            "info-inline-desc",
+            "license-section",
+            "separator",
+            "toc"
+        ].join(",")
+    );
+    return summaryElement;
+}
+
+/**
+ * Creates a `api-endpoint-documentation` web element from web API and current selection.
+ */
+export function createEndpointElement(
+    amf: Json,
+    endpointModel: Json,
+    selected: string
+): HTMLElement {
+    const el: ApiEndpointElement = document.createElement(
+        "api-endpoint-documentation"
+    ) as ApiEndpointElement;
+    el.amf = amf;
+    el.inlineMethods = false;
+    el.noNavigation = true;
+    el.selected = selected;
+    el.endpoint = endpointModel;
+    el.noTryIt = true;
+    return el;
+}
+
+/**
+ * Creates a `api-method-documentation` web element from web API and current selection.
+ */
+export function createMethodElement(
+    amf: Json,
+    endpointMethodModel: Json,
+    methodModel: Json
+): HTMLElement {
+    const el: ApiMethodElement = document.createElement(
+        "api-method-documentation"
+    ) as ApiMethodElement;
+    el.amf = amf;
+    el.noNavigation = true;
+    el.endpoint = endpointMethodModel;
+    el.method = methodModel;
+    el.noTryIt = true;
+    el.setAttribute("renderSecurity", "");
+    el.setAttribute("renderCodeSnippets", "");
+    return el;
+}
+
+/**
+ * Creates a documentation element for Security AMF type
+ *
+ */
+export function createSecurityElement(amf: Json, securityModel: Json): HTMLElement {
+    const el: ApiSecurityElement = document.createElement(
+        "api-security-documentation"
+    ) as ApiSecurityElement;
+    el.setAttribute("exportparts", ["security-title"].join(","));
+    el.amf = amf;
+    el.security = securityModel;
+    return el;
+}
+
+/**
+ * Creates a documentation element for Type AMF type
+ *
+ * @param {string} amfId Reference ID as passed in from amfConfig
+ * @param {string} selected Currently selected `@id`.
+ */
+export function createTypeElement(amf: Json, typeModel: Json, mediaTypes: Json): HTMLElement {
+    const el: ApiTypeElement = document.createElement("api-type-documentation") as ApiTypeElement;
+    el.setAttribute("exportparts", ["type-title"].join(","));
+    el.amf = amf;
+    el.type = typeModel;
+    el.mediaTypes = mediaTypes;
+    return el;
+}
+
+/**
+ * Creates a documentation element for Docs AMF type
+ *
+ * @param {string} amfId Reference ID as passed in from amfConfig
+ * @param {string} selected Currently selected `@id`.
+ */
+export function createDocumentationElement(amf: Json, docsModel: Json): HTMLElement {
+    const el: ApiDocElement = document.createElement("api-documentation-document") as ApiDocElement;
+    el.amf = amf;
+    el.shape = docsModel;
+    return el;
+}

package/src/modules/doc/content/content.ts

@@ -109,180 +109,174 @@ export default class Content extends LightningElement {
     insertDocHtml(docContent?: string) {
         const divEl = this.getCleanContainer();
 
-        // Some simple data mutation to make Prism work on-the-fly with the existing datasource
-        const templateEl = document.createElement("template");
-        // eslint-disable-next-line no-use-before-define
-        templateEl.innerHTML = docContent || this.docContent;
-
-        // Query the code blocks and create a dx-code-block component that contains the code
-        const codeBlockEls =
-            templateEl.content.querySelectorAll(".codeSection");
-        codeBlockEls.forEach((codeBlockEl) => {
-            codeBlockEl.setAttribute("lwc:dom", "manual");
-            const classList = codeBlockEl.firstChild.classList;
-            let language = "";
-            for (const key in classList) {
-                if (typeof classList[key] === "string") {
-                    const className = classList[key];
-                    if (className.startsWith("brush:")) {
-                        language = className.split(":")[1];
+        if (divEl) {
+            divEl.innerHTML = docContent || this.docContent;
+
+            // Query the code blocks and create a dx-code-block component that contains the code
+            const codeBlockEls = divEl.querySelectorAll(".codeSection");
+            codeBlockEls.forEach((codeBlockEl) => {
+                codeBlockEl.setAttribute("lwc:dom", "manual");
+                const classList = codeBlockEl.firstChild.classList;
+                let language = "";
+                for (const key in classList) {
+                    if (typeof classList[key] === "string") {
+                        const className = classList[key];
+                        if (className.startsWith("brush:")) {
+                            language = className.split(":")[1];
+                        }
                     }
                 }
-            }
-            const blockCmp = createElement("dx-code-block", { is: CodeBlock });
-            Object.assign(blockCmp, {
-                codeBlock: codeBlockEl.innerHTML,
-                // ! Hot fix for incoming html tags from couchdb for xml blocks, fix me soon please
-                language: LANGUAGE_MAP[language] || language,
-                theme: this.codeBlockTheme,
-                title: "", // Default no title.
-                variant: this.codeBlockType,
-                isEncoded: true
+                const blockCmp = createElement("dx-code-block", {
+                    is: CodeBlock
+                });
+                Object.assign(blockCmp, {
+                    codeBlock: codeBlockEl.innerHTML,
+                    // ! Hot fix for incoming html tags from couchdb for xml blocks, fix me soon please
+                    language: LANGUAGE_MAP[language] || language,
+                    theme: this.codeBlockTheme,
+                    title: "", // Default no title.
+                    variant: this.codeBlockType,
+                    isEncoded: true
+                });
+                // eslint-disable-next-line no-use-before-define
+                codeBlockEl.innerHTML = "";
+                codeBlockEl.appendChild(blockCmp);
             });
-            // eslint-disable-next-line no-use-before-define
-            codeBlockEl.innerHTML = "";
-            codeBlockEl.appendChild(blockCmp);
-        });
 
-        // Query the callouts and create a doc-content-callout component that contains the code
-        const calloutEls = templateEl.content.querySelectorAll(".message");
-        calloutEls.forEach((calloutEl) => {
-            const calloutCompEl = createElement("doc-content-callout", {
-                is: ContentCallout
-            });
-            const detailEls = calloutEl.querySelectorAll(
-                "p, div.data, ol, ul, .codeSection, .mediaBd > span.ph"
-            );
-            detailEls.forEach((detailEl) => {
-                calloutCompEl.appendChild(detailEl);
-            });
-            const type = calloutEl.querySelector("h4").textContent;
-            const typeLower = type.toLowerCase();
-            Object.assign(calloutCompEl, {
-                title: type,
-                variant: typeLower
+            // Query the callouts and create a doc-content-callout component that contains the code
+            const calloutEls = divEl.querySelectorAll(".message");
+            calloutEls.forEach((calloutEl) => {
+                const calloutCompEl = createElement("doc-content-callout", {
+                    is: ContentCallout
+                });
+                const detailEls = calloutEl.querySelectorAll(
+                    "p, div.data, ol, ul, .codeSection, .mediaBd > span.ph"
+                );
+                detailEls.forEach((detailEl) => {
+                    calloutCompEl.appendChild(detailEl);
+                });
+                const type = calloutEl.querySelector("h4").textContent;
+                const typeLower = type.toLowerCase();
+                Object.assign(calloutCompEl, {
+                    title: type,
+                    variant: typeLower
+                });
+                // eslint-disable-next-line no-use-before-define
+                calloutEl.innerHTML = "";
+                calloutEl.appendChild(calloutCompEl);
             });
-            // eslint-disable-next-line no-use-before-define
-            calloutEl.innerHTML = "";
-            calloutEl.appendChild(calloutCompEl);
-        });
 
-        // Modify links to work with any domain, links that start with "#" are excluded
-        const anchorEls =
-            templateEl.content.querySelectorAll("a:not([href^='#'])");
-
-        anchorEls.forEach((anchorEl) => {
-            if (
-                anchorEl.textContent.includes("Next →") ||
-                anchorEl.textContent.includes("← Previous")
-            ) {
-                if (this.showPaginationButtons) {
-                    this.renderPaginationButton(anchorEl);
-                } else {
-                    anchorEl.remove();
-                }
-            }
-
-            // ! This is a hack
-            // Normalize urls in case it doesn't come complete.
-            if (anchorEl.href.startsWith("atlas.")) {
-                anchorEl.href = "/docs/" + anchorEl.href;
-            }
-
-            const href = anchorEl.href.split("/");
-            if (
-                (href[3] === this.pageReference.docId && this.isStorybook) ||
-                href[4] === this.pageReference.docId ||
-                href[6] === this.pageReference.docId
-            ) {
-                let updatedURL;
-                switch (href.length) {
-                    case 8:
-                        updatedURL = href.splice(5).join("/");
-                        break;
-                    case 7:
-                        updatedURL = href.splice(4).join("/");
-                        break;
-                    case 6:
-                        updatedURL = href.splice(3).join("/");
-                        break;
-                    default:
-                        updatedURL = href.splice(6).join("/");
-                        break;
+            // Modify links to work with any domain, links that start with "#" are excluded
+            const anchorEls = divEl.querySelectorAll("a:not([href^='#'])");
+
+            anchorEls.forEach((anchorEl) => {
+                if (
+                    anchorEl.textContent.includes("Next →") ||
+                    anchorEl.textContent.includes("← Previous")
+                ) {
+                    if (this.showPaginationButtons) {
+                        this.renderPaginationButton(anchorEl);
+                    } else {
+                        anchorEl.remove();
+                    }
                 }
-                anchorEl.addEventListener(
-                    "click",
-                    // eslint-disable-next-line no-use-before-define
-                    this.handleNavClick.bind(this)
-                );
-                // anchor href event is not propagated here as we want SPA nature.
-                // But in prerender.io - as javascript is not executed, we want the anchor links are proper (absolute urls).
-                anchorEl.setAttribute("href", "/docs/" + updatedURL);
-                anchorEl.setAttribute("data-id", "docs/" + updatedURL);
-                return;
-            }
-
-            anchorEl.setAttribute("data-id", anchorEl.href);
-        });
 
-        // Modify image src to work with any domain and replace images/iframes with doc-content-media
-        const imgEls = templateEl.content.querySelectorAll("img, iframe");
-
-        imgEls.forEach((mediaEl) => {
-            const isImage = mediaEl.nodeName === "IMG";
-            let src = mediaEl.getAttribute("src");
-            if (!src) {
-                return;
-            }
-            const alt = mediaEl.getAttribute("alt");
-            const title = mediaEl.getAttribute("title");
-            const label = mediaEl.getAttribute("label");
-            const width = mediaEl.getAttribute("width");
-            const height = mediaEl.getAttribute("height");
-
-            if (isImage) {
-                src = src.startsWith("/")
-                    ? `https://developer.salesforce.com${src}`
-                    : src.replace(
-                          window.location.origin,
-                          "https://developer.salesforce.com"
-                      );
-
-                const img: HTMLImageElement = document.createElement("img");
-                img.src = src;
-                if (alt) {
-                    img.alt = alt;
+                // ! This is a hack
+                // Normalize urls in case it doesn't come complete.
+                if (anchorEl.href.startsWith("atlas.")) {
+                    anchorEl.href = "/docs/" + anchorEl.href;
                 }
-                if (title) {
-                    img.title = title;
-                }
-                if (height) {
-                    img.height = parseFloat(height);
-                }
-                if (width) {
-                    img.width = parseFloat(width);
+
+                const href = anchorEl.href.split("/");
+                if (
+                    (href[3] === this.pageReference.docId &&
+                        this.isStorybook) ||
+                    href[4] === this.pageReference.docId ||
+                    href[6] === this.pageReference.docId
+                ) {
+                    let updatedURL;
+                    switch (href.length) {
+                        case 8:
+                            updatedURL = href.splice(5).join("/");
+                            break;
+                        case 7:
+                            updatedURL = href.splice(4).join("/");
+                            break;
+                        case 6:
+                            updatedURL = href.splice(3).join("/");
+                            break;
+                        default:
+                            updatedURL = href.splice(6).join("/");
+                            break;
+                    }
+                    anchorEl.addEventListener(
+                        "click",
+                        // eslint-disable-next-line no-use-before-define
+                        this.handleNavClick.bind(this)
+                    );
+                    // anchor href event is not propagated here as we want SPA nature.
+                    // But in prerender.io - as javascript is not executed, we want the anchor links are proper (absolute urls).
+                    anchorEl.setAttribute("href", "/docs/" + updatedURL);
+                    anchorEl.setAttribute("data-id", "docs/" + updatedURL);
+                    return;
                 }
 
-                img.className = "content-image";
-                mediaEl.parentNode!.insertBefore(img, mediaEl);
-            } else {
-                const contentMediaEl = createElement("doc-content-media", {
-                    is: ContentMedia
-                });
-                Object.assign(contentMediaEl, {
-                    contentType: "iframe",
-                    contentSrc: src,
-                    mediaTitle: alt || title || label
-                });
-                mediaEl.parentNode!.insertBefore(contentMediaEl, mediaEl);
-            }
-            mediaEl.remove();
-        });
+                anchorEl.setAttribute("data-id", anchorEl.href);
+            });
 
-        if (divEl) {
-            // eslint-disable-next-line no-use-before-define
-            divEl.innerHTML = "";
-            divEl.append(templateEl.content);
+            // Modify image src to work with any domain and replace images/iframes with doc-content-media
+            const imgEls = divEl.querySelectorAll("img, iframe");
+
+            imgEls.forEach((mediaEl) => {
+                const isImage = mediaEl.nodeName === "IMG";
+                let src = mediaEl.getAttribute("src");
+                if (!src) {
+                    return;
+                }
+                const alt = mediaEl.getAttribute("alt");
+                const title = mediaEl.getAttribute("title");
+                const label = mediaEl.getAttribute("label");
+                const width = mediaEl.getAttribute("width");
+                const height = mediaEl.getAttribute("height");
+
+                if (isImage) {
+                    src = src.startsWith("/")
+                        ? `https://developer.salesforce.com${src}`
+                        : src.replace(
+                              window.location.origin,
+                              "https://developer.salesforce.com"
+                          );
+
+                    const img: HTMLImageElement = document.createElement("img");
+                    img.src = src;
+                    if (alt) {
+                        img.alt = alt;
+                    }
+                    if (title) {
+                        img.title = title;
+                    }
+                    if (height) {
+                        img.height = parseFloat(height);
+                    }
+                    if (width) {
+                        img.width = parseFloat(width);
+                    }
+
+                    img.className = "content-image";
+                    mediaEl.parentNode!.insertBefore(img, mediaEl);
+                } else {
+                    const contentMediaEl = createElement("doc-content-media", {
+                        is: ContentMedia
+                    });
+                    Object.assign(contentMediaEl, {
+                        contentType: "iframe",
+                        contentSrc: src,
+                        mediaTitle: alt || title || label
+                    });
+                    mediaEl.parentNode!.insertBefore(contentMediaEl, mediaEl);
+                }
+                mediaEl.remove();
+            });
         }
 
         // Once the html has been corectly modified, naviage to the page reference on the page