@salesforcedevs/docs-components - npm Package Compare versions

Comparing version 0.0.2 to 0.0.3-edit

lwc.config.json

 {
-    "modules": [{ "dir": "src/modules" }],
-    "expose": ["doc/container"]
+    "modules": [
+        { "dir": "src/modules" },
+        { "npm": "@salesforcedevs/dx-components" },
+        { "npm": "@salesforcedevs/dw-components" }
+    ],
+    "expose": [
+        "doc/amfReference",
+        "doc/breadcrumbs",
+        "doc/componentPlayground",
+        "doc/content",
+        "doc/contentCallout",
+        "doc/chat",
+        "doc/doDont",
+        "doc/contentLayout",
+        "doc/contentMedia",
+        "doc/docXmlContent",
+        "doc/lwcContentLayout",
+        "doc/header",
+        "doc/heading",
+        "doc/headingAnchor",
+        "doc/overview",
+        "doc/phase",
+        "doc/specificationContent",
+        "doc/versionPicker",
+        "doc/xmlContent",
+        "docUtils/utils"
+    ]
 }

package.json

 {
     "name": "@salesforcedevs/docs-components",
-    "version": "0.0.2",
+    "version": "0.0.3-edit",
     "description": "Docs Lightning web components for DSC",
-    "license": "UNLICENSED",
+    "license": "MIT",
     "main": "index.js",
     "engines": {
-        "node": ">= 12.x"
+        "node": "20.x"
     },
-    "files": [
-        "src/modules",
-        "lwc.config.json"
-    ],
     "publishConfig": {
-        "access": "restricted"
+        "access": "public"
     },
+    "dependencies": {
+        "@api-components/amf-helper-mixin": "4.5.29",
+        "classnames": "2.5.1",
+        "dompurify": "3.2.4",
+        "kagekiri": "1.4.2",
+        "lodash.orderby": "4.6.0",
+        "lodash.uniqby": "4.7.0",
+        "query-string": "7.1.3",
+        "sentence-case": "3.0.4"
+    },
+    "devDependencies": {
+        "@types/classnames": "2.3.1",
+        "@types/lodash.orderby": "4.6.9",
+        "@types/lodash.uniqby": "4.7.9"
+    },
     "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
 }

src/modules/doc/content/content.ts

 /* eslint-disable @lwc/lwc/no-inner-html */
-import { LightningElement, api, track } from "lwc";
-import Prism from "./prismjs";
+import { createElement, LightningElement, api, track } from "lwc";
+import { DocContent, PageReference } from "typings/custom";
+import CodeBlock from "dx/codeBlock";
+import Button from "dx/button";
+import { highlightTerms } from "dxUtils/highlight";
+import ContentCallout from "doc/contentCallout";
+import ContentMedia from "doc/contentMedia";
 
-/**
- * @element doc-content
- */
+const HIGHLIGHTABLE_SELECTOR = [
+    "p",
+    ".p",
+    ".shortdesc",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "li",
+    "dl",
+    "th",
+    "td"
+].join(",");
+
+const LANGUAGE_MAP: { [key: string]: string } = {
+    js: "javascript"
+};
+
 export default class Content extends LightningElement {
-    _docRendered: boolean = false;
-    @track docContent: any;
+    @api isStorybook: boolean = false;
+    @api pageReference!: PageReference;
+    @api codeBlockType: string = "card";
+    @api showPaginationButtons: boolean = false;
 
@@ -15,4 +39,5 @@ @api
         this._docRendered = false;
-        this.docContent = value;
+        this.docContent = (value && value.trim()) || "";
     }
+
     get docsData() {
@@ -22,50 +47,275 @@ return this.docContent;
 
-    insertDocHtml() {
-        const divEl = this.template.querySelector("div");
+    @track docContent: DocContent = "";
+    _docRendered: boolean = false;
 
-        // Some simple data mutation to make Prism work on-the-fly with the existing datasource
-        const templateEl = document.createElement("template");
-        this.docContent = this.docContent.trim();
-        templateEl.innerHTML = this.docContent;
+    connectedCallback() {
+        window.addEventListener(
+            "highlightedtermchange",
+            this.updateHighlighted
+        );
+    }
 
-        const preEls = templateEl.content.querySelectorAll("pre");
+    disconnectedCallback(): void {
+        window.removeEventListener(
+            "highlightedtermchange",
+            this.updateHighlighted
+        );
+    }
 
-        for (const preEl of preEls) {
-            const codeHTML = preEl.innerHTML;
-            const codeEl = document.createElement("code");
-            codeEl.classList.add("language-js");
-            codeEl.innerHTML = codeHTML;
-            preEl.innerHTML = "";
-            // preEl.classList.add("line-numbers"); // TODO: Re-add once we have line-numbers plugin added
-            preEl.appendChild(codeEl);
-        }
+    renderPaginationButton(anchorEl: HTMLElement) {
+        const isNext = anchorEl.textContent!.includes("Next →");
+        anchorEl.innerHTML = "";
+        const buttonEl = createElement("dx-button", { is: Button });
+        const params = isNext
+            ? { iconSymbol: "chevronright" }
+            : {
+                  iconPosition: "left",
+                  iconSymbol: "chevronleft",
+                  variant: "secondary"
+              };
+        Object.assign(buttonEl, params);
+        const textEl = document.createDocumentFragment();
+        textEl.textContent = isNext ? "Next" : "Previous";
+        buttonEl.appendChild(textEl);
+        anchorEl.appendChild(buttonEl);
+    }
 
-        const anchorEls = templateEl.content.querySelectorAll("a");
+    // We don't use any tracked field here. The challenge is that
+    // for security reasons you can't pass pure HTML via a class
+    // field to the template. Hence we manipulate the DOM manually.
+    insertDocHtml(docContent?: string) {
+        const divEl = this.getCleanContainer();
 
-        for (const anchorEl of anchorEls) {
-            const href = anchorEl.href.split("/");
-            const updatedURL = href[href.length - 1];
-            anchorEl.addEventListener("click", this.handleNavClick.bind(this));
-            anchorEl.setAttribute("href", "#");
-            anchorEl.setAttribute("data-id", updatedURL);
+        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.firstElementChild?.classList;
+                let language = "";
+                if (classList) {
+                    for (let i = 0; i < classList.length; i++) {
+                        const className = classList[i];
+                        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,
+                    header: "", // Default no title.
+                    variant: this.codeBlockType,
+                    isEncoded: true
+                });
+                // 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 = divEl.querySelectorAll(".message");
+            calloutEls.forEach((calloutEl) => {
+                const calloutCompEl = createElement("doc-content-callout", {
+                    is: ContentCallout
+                });
+                const detailEls = calloutEl.querySelectorAll(
+                    "p, .p, div.data, ol, ul, p+.codeSection, p~.codeSection, div >.codeSection, .mediaBd > span.ph"
+                );
+                detailEls.forEach((detailEl) => {
+                    if (detailEl.innerHTML.trim() !== "") {
+                        calloutCompEl.appendChild(detailEl);
+                    }
+                });
+
+                // Set a flag to 1 (true) if and only if all detailEls have no content.
+                let flag = 1;
+                for (let i: number = 0; i < detailEls.length; i++) {
+                    flag &= (detailEls[i].innerHTML.trim() === "") as any; // Dark Magic TM
+                }
+
+                if (flag) {
+                    const codeEls = calloutEl.querySelectorAll(".codeSection");
+                    codeEls.forEach((codeEl) => {
+                        calloutCompEl.appendChild(codeEl);
+                    });
+                }
+
+                const type = calloutEl.querySelector("h4")!.textContent!;
+                const typeLower = type.toLowerCase();
+                Object.assign(calloutCompEl, {
+                    header: type,
+                    variant: typeLower
+                });
+                // 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 = divEl.querySelectorAll("a:not([href^='#'])");
+
+            anchorEls.forEach((anchorEl: any) => {
+                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;
+                    }
+                    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 = 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");
+                const className = mediaEl.getAttribute("class");
+
+                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;
+                    img.alt = "";
+                    if (alt) {
+                        img.alt = alt;
+                    }
+                    if (title) {
+                        img.title = title;
+                    }
+                    if (height) {
+                        img.height = parseFloat(height);
+                    }
+                    if (width) {
+                        img.width = parseFloat(width);
+                    }
+                    if (className) {
+                        img.className = className;
+                    }
+
+                    img.className = `content-image ${img.className}`;
+                    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();
+            });
         }
 
-        // We don't use any tracked field here. The challenge is that
-        // for security reasons you can't pass pure HTML via a class
-        // field to the template. Hence we manipulate the DOM manually.
-        if (divEl) {
-            divEl.innerHTML = "";
-            divEl.append(templateEl.content);
+        // Once the html has been corectly modified, naviage to the page reference on the page
+        if (this.pageReference.hash) {
+            this.navigateToHash(this.pageReference.hash);
         }
+    }
 
-        Prism.highlightAllUnder(divEl);
+    private getCleanContainer(): HTMLElement | null {
+        const divEl = this.template.querySelector("div");
+        if (divEl?.hasChildNodes()) {
+            divEl.removeChild(divEl.firstChild!);
+        }
+
+        return divEl;
     }
 
+    isSamePage(reference: PageReference): boolean {
+        return (
+            this.pageReference.contentDocumentId ===
+                reference.contentDocumentId &&
+            this.pageReference.docId === reference.docId &&
+            this.pageReference.page === reference.page &&
+            this.pageReference.deliverable === reference.deliverable
+        );
+    }
+
     handleNavClick(event: InputEvent) {
         event.preventDefault();
+        const target = (event.currentTarget! as any).dataset.id;
+        const [page, docId, deliverable, tempContentDocumentId] =
+            target.split("/");
+        const [contentDocumentId, hash] = tempContentDocumentId.split("#");
+        const newPageReference = {
+            page: page,
+            docId: docId,
+            deliverable: deliverable,
+            contentDocumentId: contentDocumentId,
+            hash: hash
+        };
         this.dispatchEvent(
             new CustomEvent("navclick", {
                 detail: {
-                    url: event.target.dataset.id,
-                    type: "content"
+                    pageReference: newPageReference
                 },
@@ -76,11 +326,35 @@ bubbles: true,
         );
+
+        if (this.isSamePage({ ...newPageReference, domain: "" })) {
+            this.navigateToHash(window.location.hash);
+        }
     }
 
+    updateHighlighted = (event: any) =>
+        highlightTerms(
+            this.template.querySelectorAll(HIGHLIGHTABLE_SELECTOR),
+            event.detail
+        );
+
+    @api
+    public navigateToHash = (hash: String) => {
+        const splitHash = hash.split("#");
+        if (splitHash.length === 2) {
+            hash = splitHash[1];
+        }
+        const anchorEl = this.template.querySelector(`[id='${hash}']`);
+        if (anchorEl) {
+            anchorEl.scrollIntoView();
+        } else {
+            window.scrollTo({ top: 0, behavior: "smooth" });
+        }
+    };
+
     renderedCallback() {
-        if (this._docRendered) return;
-
+        if (this._docRendered) {
+            return;
+        }
         this.insertDocHtml();
-
         this._docRendered = true;
     }
 }

src/modules/doc/nav/nav.ts

 import { LightningElement, api } from "lwc";
+import {
+    AvailableLanguages,
+    AvailableVersions,
+    DocToc,
+    PageReference,
+    PdfUrl,
+    SelectedNavigationItem,
+    SelectedLanguage,
+    SelectedVersion
+} from "typings/custom";
 
-/**
- * @element doc-nav
- */
 export default class Nav extends LightningElement {
-    /*
+    @api availableLanguages!: AvailableLanguages;
+    @api selectedLanguage!: SelectedLanguage;
+    @api availableVersions!: AvailableVersions;
+    @api selectedVersion!: SelectedVersion;
+    @api selectedNavigationItem!: SelectedNavigationItem;
+    @api pdfUrl!: PdfUrl;
+    @api toc!: DocToc;
+    @api pageReference!: PageReference;
 
-    I've temporarily decoupled each property from docsData
-    
-    @api
-    set docsData(value: any) {
-        if (value.available_languages) {
-            this.availableLanguages = value.available_languages;
-        }
-        if (value.available_versions) {
-            this.availableVersions = value.available_versions;
-        }
-        if (value.pdf_url) {
-            this.pdfUrl = value.pdf_url;
-        }
-        if (value.toc) {
-            this.toc = value.toc;
-        }
+    handleSelected(event: CustomEvent) {
+        event.stopPropagation();
+        const newPageReference = { ...this.pageReference };
+        const target = event.detail.name.split("-");
+        newPageReference.contentDocumentId = target[0] + ".htm";
+        newPageReference.hash = target[1];
+        this.dispatchEvent(
+            new CustomEvent("navclick", {
+                detail: {
+                    pageReference: newPageReference
+                },
+                bubbles: true,
+                composed: true
+            })
+        );
     }
-    get docsData() {
-        return null;
-    }
-    */
-
-    @api availableLanguages = [];
-    @api availableVersions = [];
-    @api pdfUrl: string | undefined;
-    @api toc = [];
 }

src/modules/doc/toc/toc.ts

 import { LightningElement, api } from "lwc";
+import { PageReference, SelectedNavigationItem, DocToc } from "typings/custom";
 
-/**
- * @element doc-toc
- */
 export default class Toc extends LightningElement {
-    @api toc: any;
+    @api toc!: DocToc;
+    @api selectedNavigationItem!: SelectedNavigationItem;
+    @api pageReference!: PageReference;
 
     handleNavClick(event: InputEvent) {
         event.preventDefault();
+        const newPageReference = { ...this.pageReference };
+        // When moving to the new navigation component
+        //const target = event.detail.name.split('-')
+        const target = (event.currentTarget as any).dataset.id.split("-");
+        newPageReference.contentDocumentId = target[0] + ".htm";
+        newPageReference.hash = target[1];
         this.dispatchEvent(
             new CustomEvent("navclick", {
                 detail: {
-                    url: event.target.dataset.id,
-                    type: "navigation"
+                    pageReference: newPageReference
                 },
@@ -17,0 +22,0 @@ bubbles: true,

src/modules/doc/toolbar/toolbar.ts

 import { LightningElement, api } from "lwc";
+import {
+    AvailableLanguages,
+    AvailableVersions,
+    PdfUrl,
+    SelectedLanguage,
+    SelectedVersion
+} from "typings/custom";
 
-/**
- * @element doc-toolbar
- */
 export default class Toolbar extends LightningElement {
-    @api languages: string[] = [];
-    @api pdfUrl: string | undefined;
-    @api releaseVersions: string[] = [];
+    // Language Selector
+    @api availableLanguages!: AvailableLanguages;
 
+    @api selectedLanguage!: SelectedLanguage;
+
+    // Version Selector
+    @api availableVersions!: AvailableVersions;
+
+    @api selectedVersion!: SelectedVersion;
+
+    // PDF
+    @api pdfUrl!: PdfUrl;
+
+    /*
+    TODO: Update language on page load
+
+    renderedCallback(){
+        this.updateSelectedLanguage();
+    }
+
+    updateSelectedLanguage(){
+        const locale = this.selectedLanguage.locale;
+        const optionEl = this.template.querySelector(`option[name='${locale}']`);
+        console.log(JSON.stringify(optionEl));
+    }
+    */
+
     handleLanguageChange() {
-        const languageEl = this.template.querySelector("select");
-        const languageValue = languageEl[languageEl.selectedIndex].value;
-        this.dispatchEvent(
-            new CustomEvent("languageselected", {
-                detail: {
-                    version: languageValue
-                },
-                bubbles: true,
-                composed: true
-            })
-        );
+        const languageEl = this.template.querySelector(
+            "select[name=languages]"
+        ) as HTMLSelectElement;
+        if (languageEl) {
+            const languageValue = (languageEl[
+                languageEl.selectedIndex
+            ] as HTMLOptionElement).value;
+            this.dispatchEvent(
+                new CustomEvent("languageselected", {
+                    detail: {
+                        value: languageValue,
+                        type: "language"
+                    },
+                    bubbles: true,
+                    composed: true
+                })
+            );
+        }
     }
 
     handleVersionChange() {
-        const versionEl: HTMLElement | null = this.template.querySelector(
-            "select"
-        );
-        const versionValue = versionEl[versionEl.selectedIndex].value;
-        this.dispatchEvent(
-            new CustomEvent("versionselected", {
-                detail: {
-                    version: versionValue
-                },
-                bubbles: true,
-                composed: true
-            })
-        );
+        const versionEl = this.template.querySelector(
+            "select[name=versions]"
+        ) as HTMLSelectElement;
+        if (versionEl) {
+            const versionValue = (versionEl[
+                versionEl.selectedIndex
+            ] as HTMLOptionElement).value;
+            this.dispatchEvent(
+                new CustomEvent("versionselected", {
+                    detail: {
+                        value: versionValue,
+                        type: "version"
+                    },
+                    bubbles: true,
+                    composed: true
+                })
+            );
+        }
     }
 }

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

Explicitly Unlicensed Item

License

(Experimental) Something was found which is explicitly marked as unlicensed.

Found 1 instance in 1 package

Misc. License Issues

License

(Experimental) A package's licensing information has fine-grained problems.

Found 1 instance in 1 package

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

353873

464.26%

Number of package files

97

304.17%

Number of high license alerts

0

-100%

Number of medium license alerts

0

-100%

License quality

100

Infinity%

Lines of code

8791

450.81%

Number of medium quality alerts

0

-100%

Number of lines in readme file

42

Infinity%

Worsened metrics

Dependency count

8

Infinity%

Dev dependency count

3

Infinity%

Number of medium supply chain risk alerts

1

Infinity%

Dependency changes

• + Added

  @api-components/amf-helper-mixin@4.5.29

• + Added

  classnames@2.5.1

• + Added

  dompurify@3.2.4

• + Added

  kagekiri@1.4.2

• + Added

  lodash.orderby@4.6.0

• + Added

  lodash.uniqby@4.7.0

• + Added

  query-string@7.1.3

• + Added

  sentence-case@3.0.4

• + Added

  @api-components/amf-helper-mixin@4.5.29
  (transitive)

• + Added

  @types/trusted-types@2.0.7
  (transitive)

• + Added

  amf-json-ld-lib@0.0.14
  (transitive)

• + Added

  classnames@2.5.1
  (transitive)

• + Added

  decode-uri-component@0.2.2
  (transitive)

• + Added

  dompurify@3.2.4
  (transitive)

• + Added

  filter-obj@1.1.0
  (transitive)

• + Added

  kagekiri@1.4.2
  (transitive)

• + Added

  lodash.orderby@4.6.0
  (transitive)

• + Added

  lodash.uniqby@4.7.0
  (transitive)

• + Added

  lower-case@2.0.2
  (transitive)

• + Added

  no-case@3.0.4
  (transitive)

• + Added

  query-string@7.1.3
  (transitive)

• + Added

  sentence-case@3.0.4
  (transitive)

• + Added

  split-on-first@1.1.0
  (transitive)

• + Added

  strict-uri-encode@2.0.0
  (transitive)

• + Added

  tslib@2.8.1
  (transitive)

• + Added

  upper-case-first@2.0.2
  (transitive)