@salesforcedevs/docs-components 0.0.1

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

@@ -0,0 +1,378 @@
+/* eslint-disable @lwc/lwc/no-inner-html */
+import { createElement, LightningElement, api, track } from "lwc";
+import { DocContent, PageReference } from "typings/custom";
+import ContentCallout from "doc/contentCallout";
+import CodeBlock from "dx/codeBlock";
+import ContentMedia from "doc/contentMedia";
+import Button from "dx/button";
+import { highlightTerms } from "dxUtils/highlight";
+
+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 {
+    @api isStorybook: boolean = false;
+    @api pageReference!: PageReference;
+    @api codeBlockType: string = "card";
+    @api showPaginationButtons: boolean = false;
+
+    @api
+    set docsData(value) {
+        this._docRendered = false;
+        this.docContent = (value && value.trim()) || "";
+    }
+
+    get docsData() {
+        return this.docContent;
+    }
+
+    @api
+    set codeBlockTheme(value) {
+        this._codeBlockTheme = value;
+    }
+
+    get codeBlockTheme() {
+        return this._codeBlockTheme;
+    }
+
+    @track docContent: DocContent = "";
+    _codeBlockTheme: string = "dark";
+    _docRendered: boolean = false;
+    originalCodeBlockThemeValue: String = "";
+
+    connectedCallback() {
+        this.template.addEventListener(
+            "themechange",
+            this.updateTheme.bind(this) // eslint-disableline no-use-before-define
+        );
+
+        window.addEventListener(
+            "highlightedtermchange",
+            this.updateHighlighted
+        );
+    }
+
+    disconnectedCallback(): void {
+        window.removeEventListener(
+            "highlightedtermchange",
+            this.updateHighlighted
+        );
+    }
+
+    updateTheme() {
+        this._codeBlockTheme =
+            this._codeBlockTheme === "dark" ? "light" : "dark";
+        const codeBlockEls = this.template.querySelectorAll("dx-code-block");
+        codeBlockEls.forEach((codeBlockEl) => {
+            codeBlockEl.setAttribute("theme", this._codeBlockTheme);
+        });
+    }
+
+    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);
+    }
+
+    // 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();
+
+        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
+                });
+                // 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);
+                    }
+                });
+
+                let flag = 1;
+                for (let i: number = 0; i < detailEls.length; i++) {
+                    flag &= detailEls[i].innerHTML.trim() === "";
+                }
+
+                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, {
+                    title: 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) => {
+                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");
+
+                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
+        if (this.pageReference.hash) {
+            this.navigateToHash(this.pageReference.hash);
+        }
+    }
+
+    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();
+        // eslint-disable-next-line no-use-before-define
+        const target = event.currentTarget.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: {
+                    pageReference: newPageReference
+                },
+                bubbles: true,
+                composed: 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;
+        }
+        this.insertDocHtml();
+        this._docRendered = true;
+    }
+}

package/src/modules/doc/contentCallout/contentCallout.css

@@ -0,0 +1,56 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "docHelpers/status";
+
+.dx-callout {
+    border-radius: 4px;
+}
+
+.dx-callout-base {
+    background-color: var(--dx-g-gray-95);
+    border-color: var(--dx-g-gray-50);
+}
+
+.dx-callout-note {
+    background-color: var(--dx-g-blue-vibrant-95);
+    border-color: var(--dx-g-blue-vibrant-50);
+}
+
+.dx-callout-tip {
+    background-color: var(--dx-g-green-natural-95);
+    border-color: var(--dx-g-green-vibrant-60);
+}
+
+.dx-callout-caution {
+    background-color: var(--dx-g-red-natural-95);
+    border-color: var(--dx-g-red-vibrant-50);
+}
+
+.dx-callout-warning {
+    background-color: var(--dx-g-red-natural-95);
+    border-color: var(--dx-g-red-vibrant-50);
+}
+
+.dx-callout-base_section {
+    width: 100%;
+}
+
+.dx-callout-base_section-large {
+    width: 100%;
+    padding: var(--dx-g-spacing-xl);
+}
+
+/* callout column */
+
+.dx-callout-base_column {
+    display: flex;
+    flex-direction: row;
+}
+
+.dx-callout-base_column > *:not(:last-child):not(dx-type-badge-group) {
+    margin-bottom: var(--dx-g-spacing-sm);
+}
+
+.dx-callout-base_column > dx-type-badge-group {
+    margin-bottom: var(--dx-g-spacing-sm);
+}

package/src/modules/doc/contentCallout/contentCallout.html

@@ -0,0 +1,15 @@
+<template>
+    <div class={className}>
+        <div class="doc-status-icon dx-callout-icon">
+            <dx-icon symbol={iconName} size="large" color={iconColor}></dx-icon>
+        </div>
+        <div class="dx-callout-content">
+            <p class="doc-status-title dx-callout-title dx-text-body-3">
+                {title}
+            </p>
+            <span class="dx-callout-body dx-text-body-3">
+                <slot onslotchange={onSlotChange}></slot>
+            </span>
+        </div>
+    </div>
+</template>

package/src/modules/doc/contentCallout/contentCallout.ts

@@ -0,0 +1,58 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { CalloutVariant, LightningSlotElement } from "typings/custom";
+
+export default class ContentCallout extends LightningElement {
+    @api title!: string;
+    @api variant!: CalloutVariant;
+    cardVariant?: string;
+    iconName?: string;
+    iconColor?: string;
+
+    connectedCallback() {
+        switch (this.variant) {
+            case "tip":
+                this.cardVariant = "dx-callout-tip";
+                this.iconColor = "green-vibrant-60";
+                this.iconName = "success";
+                break;
+            case "warning":
+                this.cardVariant = "doc-status-container dx-callout-warning";
+                this.iconColor = "red-vibrant-50";
+                this.iconName = "warning";
+                break;
+            case "caution":
+                this.cardVariant = "dx-callout-caution";
+                this.iconColor = "red-vibrant-50";
+                this.iconName = "alert";
+                break;
+            case "important":
+                this.cardVariant = "doc-status-container dx-callout-important";
+                this.iconColor = "gray-10";
+                this.iconName = "announcement";
+                break;
+            case "note":
+            default:
+                this.cardVariant = "dx-callout-note";
+                this.iconColor = "blue-vibrant-50";
+                this.iconName = "info";
+        }
+    }
+
+    get className() {
+        return cx(
+            "dx-callout",
+            "doc-status-base",
+            "dx-callout-base_section",
+            "dx-callout-base_column",
+            this.cardVariant
+        );
+    }
+
+    private isSlotEmpty: boolean = true;
+    private onSlotChange(e: LightningSlotElement) {
+        // @ts-ignore
+        const slot = e.target;
+        this.isSlotEmpty = slot.assignedElements().length === 0;
+    }
+}

package/src/modules/doc/contentLayout/contentLayout.css

@@ -0,0 +1,98 @@
+:host {
+    --dx-c-content-vertical-spacing: var(--dx-g-spacing-lg);
+
+    display: block;
+}
+
+doc-breadcrumbs {
+    --dx-c-popover-z-index: 5;
+
+    display: block;
+    margin-bottom: var(--dx-g-spacing-2xl);
+}
+
+dx-sidebar,
+dx-sidebar-old {
+    --dx-c-sidebar-height: 100%;
+    --dx-c-sidebar-vertical-padding: var(--dx-c-content-vertical-spacing);
+
+    z-index: 6;
+}
+
+dx-toc {
+    --dx-c-toc-width: unset;
+
+    height: calc(100% - var(--dx-c-content-vertical-spacing) * 2);
+    margin: var(--dx-c-content-vertical-spacing) 0;
+    overflow-y: auto;
+}
+
+dx-sidebar,
+dx-toc {
+    display: block;
+}
+
+.content {
+    display: flex;
+}
+
+.content-body-doc-phase-container {
+    flex: 1;
+}
+
+.content-body-container {
+    display: flex;
+    flex-direction: row;
+    padding-right: var(--dx-g-page-padding-horizontal);
+}
+
+.content-body {
+    margin: var(--dx-g-spacing-sm) var(--dx-c-content-vertical-spacing)
+        var(--dx-g-spacing-xl);
+    flex: 1;
+    width: 0;
+}
+
+.is-sticky {
+    height: 100vh;
+    position: sticky;
+    top: 0;
+}
+
+.right-nav-bar {
+    max-width: 275px;
+}
+
+@media screen and (max-width: 1024px) {
+    .right-nav-bar {
+        display: none;
+    }
+}
+
+@media screen and (max-width: 800px) {
+    .content-body {
+        margin-top: var(--dx-c-content-vertical-spacing);
+    }
+}
+
+@media screen and (max-width: 768px) {
+    .content {
+        flex-direction: column;
+    }
+
+    .content-body-container {
+        padding-right: 0;
+    }
+
+    .left-nav-bar {
+        --dx-c-sidebar-height: 80vh;
+
+        height: unset;
+        z-index: 10;
+    }
+
+    .content-body {
+        margin-left: var(--dx-g-spacing-mlg, 20px);
+        margin-right: var(--dx-g-spacing-mlg, 20px);
+    }
+}

package/src/modules/doc/contentLayout/contentLayout.html

@@ -0,0 +1,50 @@
+<template>
+    <div class="content">
+        <template if:true={useOldSidebar}>
+            <dx-sidebar-old
+                class="is-sticky left-nav-bar"
+                trees={sidebarContent}
+                value={sidebarValue}
+                header={sidebarHeader}
+            >
+                <slot name="sidebar-header" slot="header"></slot>
+            </dx-sidebar-old>
+        </template>
+        <template if:false={useOldSidebar}>
+            <dx-sidebar
+                class="is-sticky left-nav-bar"
+                trees={sidebarContent}
+                value={sidebarValue}
+                header={sidebarHeader}
+                coveo-organization-id={coveoOrganizationId}
+                coveo-public-access-token={coveoPublicAccessToken}
+                coveo-search-hub={coveoSearchHub}
+                coveo-advanced-query-config={coveoAdvancedQueryConfig}
+            >
+                <slot name="sidebar-header" slot="header"></slot>
+            </dx-sidebar>
+        </template>
+        <div class="content-body-doc-phase-container">
+            <slot name="doc-phase"></slot>
+            <div class="content-body-container">
+                <div class="content-body">
+                    <doc-breadcrumbs
+                        if:true={showBreadcrumbs}
+                        breadcrumbs={breadcrumbs}
+                    ></doc-breadcrumbs>
+                    <div style={docContentStyle}>
+                        <slot onslotchange={onSlotChange}></slot>
+                    </div>
+                </div>
+                <div class="right-nav-bar is-sticky">
+                    <dx-toc
+                        if:true={showToc}
+                        title={tocTitle}
+                        options={tocOptions}
+                        value={tocValue}
+                    ></dx-toc>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>