@salesforcedevs/docs-components 0.56.2 → 0.56.3-example

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

@@ -8,10 +8,12 @@ type BreadcrumbConfig = {
 };
 
 const GAP = 8;
+
+// Unit in pixels based on Salesforce Sans font-family.
 const CONSTANTS = {
-    pixelPerCharacter: 7.2,
-    pixelPerCrumbSpace: GAP * 2 + 4.6,
-    minWidthPerCrumb: 245,
+    pixelPerCharacter: 7.7,
+    pixelPerCrumbSpace: GAP * 2 + 8.6,
+    minWidthPerCrumb: 200,
     dropdownWidth: 32
 };
 
@@ -22,19 +24,30 @@ export default class Breadcrumbs extends LightningElement {
     get breadcrumbs(): Breadcrumb[] {
         return this._breadcrumbs;
     }
+
     set breadcrumbs(value) {
-        this._breadcrumbs = toJson(value) || [];
+        this.normalizeAndAssignBreadcrumbs(value);
         this.calculateBreadcrumbsConfigs();
-        if (this.observer) {
-            this.updateDropdownOptionAmount();
+        if (this.isRendered) {
+            this.onWidthOrContentChange();
         }
     }
 
+    @api
+    get pixelPerCharacter(): number {
+        return this._pixelPerCharacter;
+    }
+
+    set pixelPerCharacter(value: number | string) {
+        this._pixelPerCharacter = +value;
+    }
+
     private _breadcrumbs: Breadcrumb[] = [];
+    private _pixelPerCharacter = CONSTANTS.pixelPerCharacter;
     private navWidth = 0;
-    private observer: ResizeObserver | null = null;
     private breadcrumbConfigs: BreadcrumbConfig[] = [];
     private dropdownOptionAmount? = 0;
+    private isRendered = false;
 
     private get renderSmallVariant(): boolean {
         return (
@@ -65,14 +78,14 @@ export default class Breadcrumbs extends LightningElement {
     private get dropdownOptions(): OptionWithLink[] {
         return this.breadcrumbs!.slice(1, this.dropdownOptionAmount! + 1).map(
             (link) => ({
-                id: link.href!,
+                id: link.id!,
                 label: link.label,
                 link: { href: link.href! }
             })
         );
     }
 
-    private get renderFirstCrumb(): boolean {
+    private get displayCrumbs(): boolean {
         return this.breadcrumbs.length > 1;
     }
 
@@ -80,27 +93,52 @@ export default class Breadcrumbs extends LightningElement {
         return this.breadcrumbs[0];
     }
 
+    private get breadcrumbLabels(): string {
+        return this.breadcrumbs.map((crumb) => crumb.label).join(":");
+    }
+
     private get lastCrumb(): Breadcrumb {
         return this.breadcrumbs[this.breadcrumbs.length - 1];
     }
 
+    // this payload is only used for breadcrumb dropdown
+    private get ANALYTICS_PAYLOAD() {
+        return {
+            element_type: "link",
+            nav_type: "breadcrumb",
+            nav_level: 1
+        };
+    }
+
+    private onWidthOrContentChange = () => {
+        this.navWidth = this.template
+            .querySelector("nav")!
+            .getBoundingClientRect().width;
+        this.updateDropdownOptionAmount();
+    };
+
     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")!);
-        }
+        this.isRendered = true;
+        this.onWidthOrContentChange();
+        window.addEventListener("resize", this.onWidthOrContentChange);
     }
 
     disconnectedCallback(): void {
-        this.observer?.disconnect();
+        window.removeEventListener("resize", this.onWidthOrContentChange);
+    }
+
+    private normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {
+        if (!breadcrumbs) {
+            return;
+        }
+
+        this._breadcrumbs = toJson(breadcrumbs).map(
+            (crumb: Breadcrumb, index: number) => ({
+                ...crumb,
+                id: crumb.id || crumb.href,
+                level: index
+            })
+        );
     }
 
     private updateDropdownOptionAmount(): void {
@@ -135,7 +173,8 @@ export default class Breadcrumbs extends LightningElement {
             (previousValue, element) =>
                 previousValue +
                 Math.min(
-                    element.label.length * CONSTANTS.pixelPerCharacter,
+                    element.label.length *
+                        (this.pixelPerCharacter || CONSTANTS.pixelPerCharacter),
                     CONSTANTS.minWidthPerCrumb
                 ),
             (breadcrumbs.length - 1) * CONSTANTS.pixelPerCrumbSpace + offset

package/src/modules/doc/componentPlayground/componentPlayground.css

@@ -0,0 +1,22 @@
+@import "dxHelpers/reset";
+
+/**
+ * Designs link - https://www.figma.com/design/9SalRPlJmtRDZHq03o8dL1/One-Doc-Site-Visionary-Mocks?node-id=9968-366397&m=dev
+ * Preview padding: 24px
+ * Example Selector height: 122px
+ * Example Preview min height: 150px
+ * Tab height with border: 46px(45px height and 1px border)
+ * Codeblock height: 264px(224px for codeblock and 40px for panel)
+ * Total: 606px
+**/
+
+iframe {
+    width: 100%;
+    height: 606px;
+    border-radius: var(--dx-g-spacing-sm);
+    border: 1px solid var(--dx-g-gray-90);
+}
+
+.playground-container {
+    position: relative;
+}

package/src/modules/doc/componentPlayground/componentPlayground.html

@@ -0,0 +1,20 @@
+<template>
+    <div class="playground-container" lwc:if={playgroundAvailable}>
+        <dx-spinner
+            size="large"
+            variant="brand"
+            if:true={isLoading}
+        ></dx-spinner>
+        <iframe
+            src={playgroundSrc}
+            onload={handleIframeLoad}
+            title={playgroundTitle}
+            allow="clipboard-write"
+        ></iframe>
+    </div>
+    <dx-error-fallback
+        lwc:else
+        title="Code Examples Unavailable"
+        description="This component's code examples are currently unavailable. Please check again later."
+    ></dx-error-fallback>
+</template>

package/src/modules/doc/componentPlayground/componentPlayground.ts

@@ -0,0 +1,42 @@
+import { LightningElement, api } from "lwc";
+
+export default class ComponentPlayground extends LightningElement {
+    @api model!: string;
+    @api namespace!: string;
+    @api component!: string;
+    @api playgroundAppUrl!: string;
+
+    isLoading = true;
+
+    /**
+     * Returns a formatted title for the component playground
+     * Maps 'aura' model to 'Aura' and 'lwc' model to 'Lightning'
+     * Capitalizes the first letter of the component name
+     * @returns {string} Formatted playground title
+     */
+    get playgroundTitle() {
+        const modelName = this.model === "aura" ? "Aura" : "Lightning";
+        const componentName =
+            this.component.charAt(0).toUpperCase() + this.component.slice(1);
+        return `Example previews and code for ${modelName} ${componentName} component`;
+    }
+
+    get playgroundAvailable() {
+        return (
+            this.playgroundAppUrl &&
+            this.model &&
+            this.namespace &&
+            this.component
+        );
+    }
+
+    get playgroundSrc(): string {
+        return `${this.playgroundAppUrl}/playground/${this.model}/${
+            this.namespace
+        }/${this.component.toLowerCase()}.html`;
+    }
+
+    handleIframeLoad() {
+        this.isLoading = false;
+    }
+}

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

@@ -6,8 +6,8 @@
 
 @import "dxHelpers/text";
 @import "dxHelpers/reset";
-@import "dxHelpers/card";
 @import "dxHelpers/table";
+@import "docHelpers/imgStyle";
 
 .doc-content {
     width: 100%;
@@ -31,11 +31,6 @@
     margin-bottom: var(--dx-g-spacing-md);
 }
 
-.helpHead2 {
-    margin-top: 36px;
-    margin-bottom: var(--dx-g-spacing-md);
-}
-
 .relinfo {
     padding-top: var(--dx-g-spacing-sm);
     padding-bottom: var(--dx-g-spacing-sm);
@@ -46,17 +41,10 @@
     padding-bottom: var(--dx-g-spacing-sm);
 }
 
-img.content-image {
-    height: auto;
-    display: unset;
-}
-
 .image-block .content-image {
     margin-top: var(--dx-g-spacing-lg);
     margin-bottom: var(--dx-g-spacing-sm);
     display: block;
-    margin-left: auto;
-    margin-right: auto;
 }
 
 td > img.content-image:first-child:last-child[alt="Yes"],
@@ -64,61 +52,61 @@ td > img.content-image:first-child:last-child[alt="No"] {
     width: var(--dx-g-spacing-md);
 }
 
-h1 {
-    font-family: var(--dx-g-font-display);
-    font-size: var(--dx-g-text-4xl);
-
-    /* not registered */
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
     color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: -0.4px;
-    line-height: 56px;
+    font-family: var(--dx-g-font-display);
+    font-weight: var(--dx-g-font-demi);
 }
 
-h2 {
-    font-family: var(--dx-g-font-display);
+h1 {
     font-size: var(--dx-g-text-3xl);
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: -0.1px;
+    letter-spacing: -0.8px;
     line-height: var(--dx-g-spacing-3xl);
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
 }
 
-h3 {
-    font-family: var(--dx-g-font-display);
-    font-size: 32px;
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: -0.1px;
+h2 {
+    font-size: var(--dx-g-text-2xl);
+    letter-spacing: -0.4px;
     line-height: var(--dx-g-spacing-2xl);
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
 }
 
-h4 {
-    font-family: var(--dx-g-font-display);
+h3 {
     font-size: var(--dx-g-text-xl);
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: 0;
+    letter-spacing: -0.4px;
     line-height: var(--dx-g-spacing-xl);
+    margin: var(--dx-g-spacing-xl) 0 var(--dx-g-spacing-md) 0;
+}
+
+h4 {
+    font-size: var(--dx-g-text-base);
+    letter-spacing: -0.5px;
+    line-height: var(--dx-g-spacing-lg);
+    margin: var(--dx-g-spacing-lg) 0 var(--dx-g-spacing-sm) 0;
 }
 
 h5 {
-    font-family: var(--dx-g-font-display);
-    font-size: var(--dx-g-text-lg);
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: 0;
-    line-height: 28px;
+    font-size: var(--dx-g-text-sm);
+    letter-spacing: -0.3px;
+    line-height: var(--dx-g-spacing-mlg);
+    margin: var(--dx-g-spacing-md) 0 var(--dx-g-spacing-sm) 0;
 }
 
 h6 {
-    font-family: var(--dx-g-font-display);
-    font-size: var(--dx-g-text-base);
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: 0;
-    line-height: var(--dx-g-spacing-mlg);
+    font-size: var(--dx-g-text-xs);
+    letter-spacing: -0.3px;
+    line-height: var(--dx-g-spacing-md);
+    margin: var(--dx-g-spacing-sm) 0 var(--dx-g-spacing-sm) 0;
 }
 
-.dx-text-heading-alt-1 {
-    color: var(--dx-g-gray-30);
-    font-family: var(--dx-g-font-sans);
-    font-size: var(--slds-text-lg);
-    line-height: 25px;
+img {
+    image-rendering: optimize-contrast;
 }
 
 p,
@@ -165,10 +153,6 @@ a,
     color: var(--dx-g-blue-vibrant-50);
 }
 
-.helpHead1 {
-    margin-bottom: var(--dx-g-spacing-lg);
-}
-
 .shortdesc {
     font-family: var(--dx-g-font-sans);
     font-size: var(--dx-g-text-base);
@@ -270,6 +254,10 @@ li {
         var(--dx-g-spacing-lg);
 }
 
+li table {
+    margin-bottom: var(--dx-g-spacing-lg);
+}
+
 li > li {
     margin-left: var(--dx-g-spacing-2xl);
 }
@@ -283,27 +271,6 @@ a:hover,
     text-decoration: underline;
 }
 
-@media (max-width: 640px) {
-    /* Mobile */
-    img.content-image {
-        max-width: 95vw;
-    }
-}
-
-@media (min-width: 641px) {
-    /* Tablet (medium) */
-    img.content-image {
-        max-width: 80vw;
-    }
-}
-
-@media (min-width: 769px) {
-    /* Desktop */
-    img.content-image {
-        max-width: min(60vw, 650px);
-    }
-}
-
 ul,
 ol {
     margin-left: var(--dx-g-spacing-lg);
@@ -376,13 +343,30 @@ ul ul ul ul ul ul {
     margin: var(--dx-g-spacing-lg) 0;
 }
 
-figure {
+figure,
+.fig {
     margin: var(--dx-g-spacing-lg) 0;
+    text-align: left;
+    display: flex;
+    flex-direction: column;
+    align-items: left;
+    justify-content: left;
 }
 
-figcaption {
+figcaption,
+.figcap {
+    display: block;
     font-size: var(--dx-g-text-xs);
-    margin-top: var(--dx-g-spacing-sm);
+    margin: var(--dx-g-spacing-sm) 0;
+    order: 2;
+}
+
+.figcap .image {
+    order: 1;
+}
+
+.fig.fig-centered {
+    text-align: center;
 }
 
 code,
@@ -397,3 +381,13 @@ samp,
 mark {
     background-color: var(--dx-g-yellow-vibrant-90);
 }
+
+/* offset page jump link due to fixed header */
+[id] {
+    --dx-c-content-scroll-margin-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+            var(--dx-g-spacing-2xl)
+    );
+
+    scroll-margin-top: var(--dx-c-content-scroll-margin-top);
+}

package/src/modules/doc/content/content.html

@@ -1,4 +1,5 @@
 <template>
+    <dx-redirect-checker></dx-redirect-checker>
     <template if:true={docsData}>
         <div class="container" data-name="content" lwc:dom="manual"></div>
     </template>

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

@@ -1,11 +1,11 @@
 /* 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";
+import ContentCallout from "doc/contentCallout";
+import ContentMedia from "doc/contentMedia";
 
 const HIGHLIGHTABLE_SELECTOR = [
     "p",
@@ -43,26 +43,10 @@ export default class Content extends LightningElement {
         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
@@ -76,17 +60,8 @@ export default class Content extends LightningElement {
         );
     }
 
-    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 →");
+        const isNext = anchorEl.textContent!.includes("Next →");
         anchorEl.innerHTML = "";
         const buttonEl = createElement("dx-button", { is: Button });
         const params = isNext
@@ -116,11 +91,11 @@ export default class Content extends LightningElement {
             const codeBlockEls = divEl.querySelectorAll(".codeSection");
             codeBlockEls.forEach((codeBlockEl) => {
                 codeBlockEl.setAttribute("lwc:dom", "manual");
-                const classList = codeBlockEl.firstChild.classList;
+                const classList = codeBlockEl.firstElementChild?.classList;
                 let language = "";
-                for (const key in classList) {
-                    if (typeof classList[key] === "string") {
-                        const className = classList[key];
+                if (classList) {
+                    for (let i = 0; i < classList.length; i++) {
+                        const className = classList[i];
                         if (className.startsWith("brush:")) {
                             language = className.split(":")[1];
                         }
@@ -133,8 +108,7 @@ export default class Content extends LightningElement {
                     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.
+                    header: "", // Default no title.
                     variant: this.codeBlockType,
                     isEncoded: true
                 });
@@ -150,7 +124,7 @@ export default class Content extends LightningElement {
                     is: ContentCallout
                 });
                 const detailEls = calloutEl.querySelectorAll(
-                    "p, div.data, ol, ul, p+.codeSection, .mediaBd > span.ph"
+                    "p, .p, div.data, ol, ul, p+.codeSection, p~.codeSection, div >.codeSection, .mediaBd > span.ph"
                 );
                 detailEls.forEach((detailEl) => {
                     if (detailEl.innerHTML.trim() !== "") {
@@ -158,9 +132,10 @@ export default class Content extends LightningElement {
                     }
                 });
 
+                // Set a flag to 1 (true) if and only if all detailEls have no content.
                 let flag = 1;
-                for (let i = 0; i < detailEls.length; i++) {
-                    flag &= detailEls[i].innerHTML.trim() === "";
+                for (let i: number = 0; i < detailEls.length; i++) {
+                    flag &= (detailEls[i].innerHTML.trim() === "") as any; // Dark Magic TM
                 }
 
                 if (flag) {
@@ -170,10 +145,10 @@ export default class Content extends LightningElement {
                     });
                 }
 
-                const type = calloutEl.querySelector("h4").textContent;
+                const type = calloutEl.querySelector("h4")!.textContent!;
                 const typeLower = type.toLowerCase();
                 Object.assign(calloutCompEl, {
-                    title: type,
+                    header: type,
                     variant: typeLower
                 });
                 // eslint-disable-next-line no-use-before-define
@@ -184,10 +159,10 @@ export default class Content extends LightningElement {
             // Modify links to work with any domain, links that start with "#" are excluded
             const anchorEls = divEl.querySelectorAll("a:not([href^='#'])");
 
-            anchorEls.forEach((anchorEl) => {
+            anchorEls.forEach((anchorEl: any) => {
                 if (
-                    anchorEl.textContent.includes("Next →") ||
-                    anchorEl.textContent.includes("← Previous")
+                    anchorEl.textContent!.includes("Next →") ||
+                    anchorEl.textContent!.includes("← Previous")
                 ) {
                     if (this.showPaginationButtons) {
                         this.renderPaginationButton(anchorEl);
@@ -253,6 +228,7 @@ export default class Content extends LightningElement {
                 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("/")
@@ -264,6 +240,7 @@ export default class Content extends LightningElement {
 
                     const img: HTMLImageElement = document.createElement("img");
                     img.src = src;
+                    img.alt = "";
                     if (alt) {
                         img.alt = alt;
                     }
@@ -276,8 +253,11 @@ export default class Content extends LightningElement {
                     if (width) {
                         img.width = parseFloat(width);
                     }
+                    if (className) {
+                        img.className = className;
+                    }
 
-                    img.className = "content-image";
+                    img.className = `content-image ${img.className}`;
                     mediaEl.parentNode!.insertBefore(img, mediaEl);
                 } else {
                     const contentMediaEl = createElement("doc-content-media", {
@@ -321,8 +301,7 @@ export default class Content extends LightningElement {
 
     handleNavClick(event: InputEvent) {
         event.preventDefault();
-        // eslint-disable-next-line no-use-before-define
-        const target = event.currentTarget.dataset.id;
+        const target = (event.currentTarget! as any).dataset.id;
         const [page, docId, deliverable, tempContentDocumentId] =
             target.split("/");
         const [contentDocumentId, hash] = tempContentDocumentId.split("#");
@@ -355,7 +334,7 @@ export default class Content extends LightningElement {
         );
 
     @api
-    public navigateToHash(hash: String) {
+    public navigateToHash = (hash: String) => {
         const splitHash = hash.split("#");
         if (splitHash.length === 2) {
             hash = splitHash[1];
@@ -366,7 +345,7 @@ export default class Content extends LightningElement {
         } else {
             window.scrollTo({ top: 0, behavior: "smooth" });
         }
-    }
+    };
 
     renderedCallback() {
         if (this._docRendered) {