@salesforcedevs/docs-components 0.43.3-sidebar-scroll → 0.49.1-alpha.0

package/lwc.config.json

@@ -4,6 +4,7 @@
         { "npm": "@salesforcedevs/dx-components" }
     ],
     "expose": [
+        "doc/breadcrumbs",
         "doc/contentCallout",
         "doc/contentMedia",
         "doc/content",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "0.43.3-sidebar-scroll",
+    "version": "0.49.1-alpha.0",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",

package/src/modules/doc/breadcrumbItem/breadcrumbItem.css

@@ -0,0 +1,50 @@
+@import "helpers/reset";
+@import "helpers/text";
+
+:host {
+    display: flex;
+    align-items: center;
+    width: fit-content;
+}
+
+:host(.breadcrumb_long) {
+    /* ensure 30 character min-width */
+    min-width: 245px;
+}
+
+:host(.breadcrumb_back-arrow) {
+    gap: var(--dx-g-spacing-sm);
+    padding: var(--dx-g-spacing-sm);
+}
+
+:host(.breadcrumb_back-arrow:hover) {
+    background-color: var(--dx-g-cloud-blue-vibrant-90);
+    border-radius: var(--dx-g-spacing-xs);
+}
+
+:host(.breadcrumb_back-arrow) :is(a, dx-icon) {
+    color: var(--dx-g-blue-vibrant-50);
+}
+
+a {
+    font-weight: var(--dx-g-font-bold);
+    text-decoration: none;
+    transition: var(--dx-g-transition-hue-1x);
+}
+
+a,
+span {
+    color: var(
+        --dx-c-breadcrumbs-breadcrumb-color,
+        var(--dx-g-blue-vibrant-20)
+    );
+    font-family: var(--dx-g-font-sans);
+    font-size: var(--dx-g-text-sm);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+a:hover {
+    color: var(--dx-g-blue-vibrant-40);
+}

package/src/modules/doc/breadcrumbItem/breadcrumbItem.html

@@ -0,0 +1,5 @@
+<template>
+    <dx-icon if:true={isBackArrowVariant} symbol="back"></dx-icon>
+    <a if:true={href} href={href}>{label}</a>
+    <span if:false={href}>{label}</span>
+</template>

package/src/modules/doc/breadcrumbItem/breadcrumbItem.ts

@@ -0,0 +1,49 @@
+import { LightningElement, api } from "lwc";
+import { BreadcrumbItemVariant } from "typings/custom";
+
+const BREADCRUMB_LONG = "breadcrumb_long";
+const BREADCRUMB_BACK_ARROW = "breadcrumb_back-arrow";
+
+const LONG_LABEL_NUMBER = 30;
+export default class BreadcrumbItem extends LightningElement {
+    @api href?: string;
+
+    @api
+    get label() {
+        return this._label;
+    }
+
+    set label(value) {
+        this._label = value;
+        this.calculateClass();
+    }
+
+    @api
+    get variant() {
+        return this._variant;
+    }
+
+    set variant(value) {
+        this._variant = value;
+        this.calculateClass();
+    }
+
+    _label: string = "";
+    _variant: BreadcrumbItemVariant = "default";
+
+    private calculateClass(): void {
+        this.classList.remove(BREADCRUMB_LONG, BREADCRUMB_BACK_ARROW);
+
+        if (this.label?.length >= LONG_LABEL_NUMBER) {
+            this.classList.add(BREADCRUMB_LONG);
+        }
+
+        if (this._variant === "back-arrow") {
+            this.classList.add(BREADCRUMB_BACK_ARROW);
+        }
+    }
+
+    private get isBackArrowVariant(): boolean {
+        return this._variant === "back-arrow";
+    }
+}

package/src/modules/doc/breadcrumbs/breadcrumbs.css

@@ -0,0 +1,19 @@
+@import "helpers/reset";
+@import "helpers/text";
+
+:host {
+    --dx-c-breadcrumbs-title-color: var(--dx-g-blue-vibrant-20);
+    --dx-c-breadcrumbs-breadcrumb-color: var(--dx-g-blue-vibrant-20);
+}
+
+nav {
+    display: flex;
+    align-items: center;
+    height: 100%;
+    position: relative;
+    gap: var(--dx-g-spacing-sm);
+}
+
+.breadcrumb-item_slash {
+    min-width: fit-content;
+}

package/src/modules/doc/breadcrumbs/breadcrumbs.html

@@ -0,0 +1,48 @@
+<template>
+    <nav role="navigation" aria-label={ariaLabel}>
+        <template if:false={renderSmallVariant}>
+            <template if:true={renderFirstCrumb}>
+                <doc-breadcrumb-item
+                    href={firstCrumb.href}
+                    label={firstCrumb.label}
+                ></doc-breadcrumb-item>
+                <span class="breadcrumb-item_slash">/</span>
+            </template>
+            <template if:true={renderDropdown}>
+                <dx-dropdown
+                    if:true={renderDropdown}
+                    options={dropdownOptions}
+                    open-on-hover
+                    placement="bottom"
+                    width="200px"
+                >
+                    <dx-button
+                        aria-label="Open Breadcrumbs Dropdown"
+                        icon-size="large"
+                        icon-symbol="threedots"
+                        variant="tertiary"
+                    ></dx-button>
+                </dx-dropdown>
+                <span class="breadcrumb-item_slash">/</span>
+            </template>
+            <template for:each={breadcrumbItems} for:item="breadcrumb">
+                <doc-breadcrumb-item
+                    href={breadcrumb.href}
+                    key={breadcrumb.label}
+                    label={breadcrumb.label}
+                ></doc-breadcrumb-item>
+                <span class="breadcrumb-item_slash" key={breadcrumb.label}>
+                    /
+                </span>
+            </template>
+            <doc-breadcrumb-item label={lastCrumb.label}></doc-breadcrumb-item>
+        </template>
+        <template if:true={renderSmallVariant}>
+            <doc-breadcrumb-item
+                href={lastLinkCrump.href}
+                label={lastLinkCrump.label}
+                variant="back-arrow"
+            ></doc-breadcrumb-item>
+        </template>
+    </nav>
+</template>

package/src/modules/doc/breadcrumbs/breadcrumbs.ts

@@ -0,0 +1,144 @@
+import { LightningElement, api } from "lwc";
+import { Breadcrumb, Option } from "typings/custom";
+import { toJson } from "utils/normalizers";
+
+type BreadcrumbConfig = {
+    minWidth: number;
+    crumbsInDropdown: number;
+};
+
+const GAP = 8;
+const CONSTANTS = {
+    pixelPerCharacter: 7.2,
+    pixelPerCrumbSpace: GAP * 2 + 4.6,
+    minWidthPerCrumb: 245,
+    dropdownWidth: 32
+};
+
+export default class Breadcrumbs extends LightningElement {
+    @api ariaLabel: string = "Documentation Breadcrumbs";
+
+    @api
+    get breadcrumbs(): Breadcrumb[] {
+        return this._breadcrumbs;
+    }
+    set breadcrumbs(value) {
+        this._breadcrumbs = toJson(value) || [];
+        this.calculateBreadcrumbsConfigs();
+        if (this.observer) {
+            this.updateDropdownOptionAmount();
+        }
+    }
+
+    private _breadcrumbs: Breadcrumb[] = [];
+    private navWidth = 0;
+    private observer: ResizeObserver | null = null;
+    private breadcrumbConfigs: BreadcrumbConfig[] = [];
+    private dropdownOptionAmount? = 0;
+
+    private get renderSmallVariant(): boolean {
+        return (
+            !this.dropdownOptionAmount &&
+            this.dropdownOptionAmount !== 0 &&
+            !!this.lastLinkCrump
+        );
+    }
+
+    private get lastLinkCrump(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 2];
+    }
+
+    private get hasInternalBreadcrumbs(): boolean {
+        return this.breadcrumbs.length > 2;
+    }
+
+    private get breadcrumbItems(): Breadcrumb[] {
+        return this.breadcrumbs!.slice(
+            this.dropdownOptionAmount! + 1,
+            this._breadcrumbs.length - 1
+        );
+    }
+
+    private get renderDropdown(): boolean {
+        return this.hasInternalBreadcrumbs && !!this.dropdownOptionAmount;
+    }
+    private get dropdownOptions(): Option[] {
+        return this.breadcrumbs!.slice(1, this.dropdownOptionAmount! + 1).map(
+            (link) => ({
+                id: link.href!,
+                label: link.label,
+                link: { href: link.href! }
+            })
+        );
+    }
+
+    private get renderFirstCrumb(): boolean {
+        return this.breadcrumbs.length > 1;
+    }
+
+    private get firstCrumb(): Breadcrumb {
+        return this.breadcrumbs[0];
+    }
+
+    private get lastCrumb(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 1];
+    }
+
+    renderedCallback(): void {
+        if (!this.observer) {
+            this.observer = new ResizeObserver((entries) => {
+                const [nav] = entries;
+                if (this.navWidth === nav.contentRect.width) {
+                    return;
+                }
+                this.navWidth = nav.contentRect.width;
+                this.updateDropdownOptionAmount();
+            });
+
+            this.observer.observe(this.template.querySelector("nav")!);
+        }
+    }
+
+    disconnectedCallback(): void {
+        this.observer?.disconnect();
+    }
+
+    private updateDropdownOptionAmount(): void {
+        this.dropdownOptionAmount = this.breadcrumbConfigs.find(
+            ({ minWidth }) => minWidth <= this.navWidth
+        )?.crumbsInDropdown;
+    }
+
+    private calculateBreadcrumbsConfigs(): void {
+        this.breadcrumbConfigs = [
+            ...Array(this._breadcrumbs.length - 1).keys()
+        ].map((optionsAmount) => {
+            const breadcrumbs = [...this._breadcrumbs];
+            breadcrumbs.splice(1, optionsAmount);
+            return {
+                crumbsInDropdown: optionsAmount,
+                minWidth: this.reduceBreadcrumbs(
+                    breadcrumbs,
+                    optionsAmount
+                        ? CONSTANTS.dropdownWidth + CONSTANTS.pixelPerCrumbSpace
+                        : 0
+                )
+            };
+        });
+    }
+
+    private reduceBreadcrumbs(
+        breadcrumbs: Breadcrumb[],
+        offset: number = 0
+    ): number {
+        return breadcrumbs.reduce(
+            (previousValue, element) =>
+                previousValue +
+                Math.min(
+                    element.label.length * CONSTANTS.pixelPerCharacter,
+                    CONSTANTS.minWidthPerCrumb
+                ),
+            (breadcrumbs.length - 1) * CONSTANTS.pixelPerCrumbSpace + offset
+        );
+    }
+}

package/src/modules/doc/content/content.css

@@ -242,7 +242,8 @@ dd {
 }
 
 li {
-    margin-left: var(--dx-g-spacing-lg);
+    margin: var(--dx-g-spacing-sm) 0 var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-lg);
 }
 
 li > li {

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