@salesforcedevs/docs-components 0.56.2-snyk → 0.56.3-example

package/package.json

@@ -1,11 +1,16 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "0.56.2-snyk",
+    "version": "0.56.3-example",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
     "engines": {
-        "node": "20.x"
+        "node": "20.x",
+        "yarn": "1.22.x"
+    },
+    "volta": {
+        "node": "20.18.2",
+        "yarn": "1.22.19"
     },
     "publishConfig": {
         "access": "public"

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

@@ -17,6 +17,6 @@ iframe {
     border: 1px solid var(--dx-g-gray-90);
 }
 
-.container {
+.playground-container {
     position: relative;
 }

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

@@ -1,5 +1,5 @@
 <template>
-    <div class="container">
+    <div class="playground-container" lwc:if={playgroundAvailable}>
         <dx-spinner
             size="large"
             variant="brand"
@@ -8,8 +8,13 @@
         <iframe
             src={playgroundSrc}
             onload={handleIframeLoad}
-            title="Component Playground"
+            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

@@ -8,6 +8,28 @@ export default class ComponentPlayground extends LightningElement {
 
     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

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

@@ -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,15 +60,6 @@ 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 →");
         anchorEl.innerHTML = "";
@@ -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 as any).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,7 +108,6 @@ 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,
                     header: "", // Default no title.
                     variant: this.codeBlockType,
                     isEncoded: true
@@ -158,6 +132,7 @@ 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: number = 0; i < detailEls.length; i++) {
                     flag &= (detailEls[i].innerHTML.trim() === "") as any; // Dark Magic TM
@@ -359,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];
@@ -370,7 +345,7 @@ export default class Content extends LightningElement {
         } else {
             window.scrollTo({ top: 0, behavior: "smooth" });
         }
-    }
+    };
 
     renderedCallback() {
         if (this._docRendered) {

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

@@ -11,6 +11,8 @@
                 language={language}
                 bail-href={bailHref}
                 bail-label={bailLabel}
+                dev-center={devCenter}
+                brand={brand}
             >
                 <slot name="sidebar-header" slot="version-picker"></slot>
             </dx-sidebar-old>
@@ -30,6 +32,8 @@
                 language={language}
                 bail-href={bailHref}
                 bail-label={bailLabel}
+                dev-center={devCenter}
+                brand={brand}
             >
                 <slot name="sidebar-header" slot="version-picker"></slot>
             </dx-sidebar>

package/src/modules/doc/contentLayout/contentLayout.ts

@@ -42,6 +42,8 @@ export default class ContentLayout extends LightningElement {
     @api language!: string;
     @api bailHref!: string;
     @api bailLabel!: string;
+    @api devCenter: any;
+    @api brand: any;
 
     // This is needed for now to prevent failing snapshot tests due to links in the footer
     @api showFooter = false;

package/src/modules/doc/header/header.html

@@ -6,6 +6,7 @@
                     lwc:if={showBanner}
                     banner-markup={bannerMarkup}
                 ></dx-banner>
+                <!-- To-Do: Move the devCenter as a new component and use it here, as devCenter is also used in Sidebar now -->
                 <div lwc:if={devCenter} class="dev-center-link">
                     <a href={devCenter.link} class="dev-center-content">
                         <dx-icon symbol="back"></dx-icon>
@@ -30,7 +31,7 @@
                         </a>
                     </div>
                     <div
-                        lwc:if={hasScopedNavItems}
+                        lwc:if={showScopedNavItems}
                         class="header_l2_group header_l2_group-nav"
                     >
                         <div
@@ -48,7 +49,7 @@
             </header>
         </dx-brand-theme-provider>
     </template>
-    <template lwc:if={showDocDivider}>
+    <template lwc:if={shouldHideHeader}>
         <div class="no-header-content"></div>
     </template>
 </template>

package/src/modules/doc/header/header.ts

@@ -1,8 +1,8 @@
 import { api } from "lwc";
 import cx from "classnames";
-import type { OptionWithNested } from "typings/custom";
+import type { OptionWithNested, DevCenterConfig } from "typings/custom";
 import { HeaderBase } from "dxBaseElements/headerBase";
-import { toJson } from "dxUtils/normalizers";
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 
 const TABLET_MATCH = "980px";
 const MOBILE_MATCH = "768px";
@@ -18,6 +18,15 @@ export default class Header extends HeaderBase {
     @api langValuePath: string = "id"; // allows to override how language property is interpreted, follows valuePath dropdown api.
     @api headerHref: string = "/";
 
+    @api
+    get hideDocHeader() {
+        return this._hideDocHeader;
+    }
+
+    set hideDocHeader(value) {
+        this._hideDocHeader = normalizeBoolean(value);
+    }
+
     @api
     get scopedNavItems() {
         return this._scopedNavItems;
@@ -28,7 +37,7 @@ export default class Header extends HeaderBase {
     }
 
     @api
-    get devCenter() {
+    get devCenter(): DevCenterConfig {
         return this._devCenter;
     }
 
@@ -41,14 +50,27 @@ export default class Header extends HeaderBase {
     private tabletMatchMedia!: MediaQueryList;
     private shouldRender: boolean = false;
     private showDocDivider: boolean = false;
-    private _devCenter: any;
+    private _devCenter!: DevCenterConfig;
+    private _hideDocHeader: boolean = false;
 
     protected mobileBreakpoint(): string {
         return MOBILE_MATCH;
     }
 
-    private get hasScopedNavItems(): boolean {
-        return this.scopedNavItems && this.scopedNavItems.length > 0;
+    private get showScopedNavItems(): boolean {
+        return (
+            this.scopedNavItems &&
+            this.scopedNavItems.length > 0 &&
+            !this.hideDocHeader
+        );
+    }
+
+    /**
+     * This function returns true if the hideDocHeader is true and the view is not mobile.
+     * Also we need to show the header border in case the doc is hidden or if the brand information doesn't exists.
+     */
+    private get shouldHideHeader(): boolean {
+        return (this.hideDocHeader && !this.mobile) || this.showDocDivider;
     }
 
     connectedCallback(): void {
@@ -60,7 +82,8 @@ export default class Header extends HeaderBase {
         this.tabletMatchMedia.addEventListener("change", this.onTabletChange);
 
         if (
-            (window.location.pathname.includes("/docs/") &&
+            (!this.shouldHideHeader &&
+                window.location.pathname.includes("/docs/") &&
                 window.location.pathname !== "/docs/apis") ||
             window.location.pathname ===
                 "/tableau/embedding-playground/overview" ||
@@ -91,7 +114,7 @@ export default class Header extends HeaderBase {
     protected additionalClasses(): string {
         return cx(
             this.brand && "has-brand",
-            this.hasScopedNavItems && "has-scoped-nav-items"
+            this.showScopedNavItems && "has-scoped-nav-items"
         );
     }
 }

package/src/modules/doc/lwcContentLayout/lwcContentLayout.html

@@ -11,6 +11,8 @@
                 language={language}
                 bail-href={bailHref}
                 bail-label={bailLabel}
+                dev-center={devCenter}
+                brand={brand}
             >
                 <slot name="sidebar-header" slot="version-picker"></slot>
             </dx-sidebar-old>
@@ -30,6 +32,8 @@
                 language={language}
                 bail-href={bailHref}
                 bail-label={bailLabel}
+                dev-center={devCenter}
+                brand={brand}
             >
                 <slot name="sidebar-header" slot="version-picker"></slot>
             </dx-sidebar>

package/src/modules/doc/lwcContentLayout/lwcContentLayout.ts

@@ -2,44 +2,111 @@ import ContentLayout from "doc/contentLayout";
 
 const TOC_HEADER_TAG = "doc-heading";
 const RNB_BY_TAB = "docs-tab";
-const SPECIFICATION_TAB_TITLE = "Specification";
+const SPECIFICATION_TAG = "doc-specification-content";
 export const OBSERVER_ATTACH_WAIT_TIME = 500;
 
 export default class LwcContentLayout extends ContentLayout {
     private rnbByTab: boolean = false;
 
+    // DOM element caches to avoid repeated queries
+    private tabPanelListCache: any = null;
+    private hasSpecContentCache: boolean | null = null;
+    private allTabsCache: any[] | null = null;
+    private mainSlotCache: any = null;
+
     private setRNBByTab() {
-        const tabPanelListItem: any = this.getTabPanelList();
-        this.rnbByTab = tabPanelListItem?.id === RNB_BY_TAB ? true : false;
+        const tabPanelListItem = this.getTabPanelList();
+        this.rnbByTab = tabPanelListItem?.id === RNB_BY_TAB;
     }
 
     get showTabBasedRNB() {
         return this.rnbByTab;
     }
 
+    /**
+     * Check if the main slot contains doc-specification-content
+     * Uses caching to avoid repeated DOM queries
+     */
+    private hasSpecificationContent(): boolean {
+        if (this.hasSpecContentCache !== null) {
+            return this.hasSpecContentCache;
+        }
+
+        const mainSlot = this.getMainSlot();
+        if (mainSlot) {
+            const assignedElements = (mainSlot as any).assignedElements();
+
+            for (const element of assignedElements) {
+                if (
+                    element.tagName === SPECIFICATION_TAG ||
+                    element.querySelector(SPECIFICATION_TAG) ||
+                    element.shadowRoot?.querySelector(SPECIFICATION_TAG)
+                ) {
+                    return (this.hasSpecContentCache = true);
+                }
+            }
+        }
+        return (this.hasSpecContentCache = false);
+    }
+
+    /**
+     * Clear all caches when content changes
+     */
+    private clearAllCaches(): void {
+        this.hasSpecContentCache = null;
+        this.tabPanelListCache = null;
+        this.allTabsCache = null;
+        this.mainSlotCache = null;
+    }
+
+    /**
+     * Get the main slot element with caching
+     */
+    private getMainSlot(): any {
+        if (!this.mainSlotCache) {
+            this.mainSlotCache =
+                this.template.querySelector("slot:not([name])");
+        }
+        return this.mainSlotCache;
+    }
+
+    /**
+     * Get tab panel list with caching
+     */
+    private getTabPanelList(): any {
+        if (!this.tabPanelListCache) {
+            // eslint-disable-next-line @lwc/lwc/no-document-query
+            this.tabPanelListCache =
+                document.querySelector("dx-tab-panel-list");
+        }
+        return this.tabPanelListCache;
+    }
+
     onRNBClick = (event: CustomEvent) => {
         event.stopPropagation();
-        const currentTab = this.getSelectedTabId();
-        if (currentTab === SPECIFICATION_TAB_TITLE) {
+        if (this.hasSpecificationContent()) {
             this.didScrollToSelectedHash = false;
         }
     };
 
     onTabChanged = () => {
         this.updateRNB();
-    };
 
-    private getTabPanelList() {
-        // eslint-disable-next-line @lwc/lwc/no-document-query
-        return document.querySelector("dx-tab-panel-list");
-    }
+        const { hash } = window.location;
+        if (this.hasSpecificationContent() && hash) {
+            this.didScrollToSelectedHash = false;
+
+            requestAnimationFrame(() => this.updateHeadingForRNB());
+        }
+    };
 
     protected getHeadingElements() {
         let headingElements = super.getHeadingElements();
         if (this.showTabBasedRNB) {
-            const tabPanelListItem: any = this.getTabPanelList();
+            const tabPanelListItem = this.getTabPanelList();
             const tabPanels =
                 tabPanelListItem?.querySelectorAll("dx-tab-panel");
+
             for (const tabPanelItem of tabPanels) {
                 if (tabPanelItem.active) {
                     // This is needed for Specification tab content
@@ -65,6 +132,7 @@ export default class LwcContentLayout extends ContentLayout {
     private updateURL() {
         const tabs = this.getAllTabs();
         const selectedTabId = this.getSelectedTabId();
+
         tabs.forEach((tab: any) => {
             if (tab.getAttribute("aria-selected") === "true") {
                 const tabID = tab.getAttribute("aria-label");
@@ -101,22 +169,38 @@ export default class LwcContentLayout extends ContentLayout {
             const selectedTabId = this.getSelectedTabId();
             if (selectedTabId) {
                 this.selectTabById(selectedTabId);
+
+                // If there's a hash and we have specification content,
+                // we need to wait for the content to load before scrolling
+                const { hash } = window.location;
+                if (this.hasSpecificationContent() && hash) {
+                    // Reset the scroll flag to allow scrolling once content is loaded
+                    this.didScrollToSelectedHash = false;
+                }
             }
         });
     }
 
     private getAllTabs(): any[] {
-        const tabPanelListItem: any = this.getTabPanelList();
+        // Return cached result if available
+        if (this.allTabsCache) {
+            return this.allTabsCache;
+        }
+
+        const tabPanelListItem = this.getTabPanelList();
         if (tabPanelListItem?.shadowRoot) {
-            return Array.from(
+            this.allTabsCache = Array.from(
                 tabPanelListItem.shadowRoot.querySelectorAll(
                     "dx-tab-panel-item"
                 )
             ).map((tabPanelItem: any) =>
                 tabPanelItem.shadowRoot.querySelector("button")
             );
+        } else {
+            this.allTabsCache = [];
         }
-        return [];
+
+        return this.allTabsCache;
     }
 
     private selectTabById(tabId: string) {
@@ -158,8 +242,12 @@ export default class LwcContentLayout extends ContentLayout {
         }
     }
 
+    onSlotChange(): void {
+        this.clearAllCaches();
+        super.onSlotChange();
+    }
+
     updateHeadingForRNB(): void {
-        // We only need to update URL in case of /docs and ignore if tabs are used anywhere else in DSC
         if (this.showTabBasedRNB) {
             this.updateURL();
         }

package/src/modules/doc/specificationContent/specificationContent.css

@@ -29,3 +29,8 @@ table {
 .icon {
     display: inline-block;
 }
+
+.loader {
+    pointer-events: none;
+    bottom: 30%;
+}

package/src/modules/doc/specificationContent/specificationContent.html

@@ -1,5 +1,12 @@
 <template>
     <div class="specification-properties">
+        <dx-spinner
+            size="large"
+            variant="brand"
+            class="loader"
+            if:true={isLoading}
+        ></dx-spinner>
+        <dx-error-fallback lwc:if={showError}></dx-error-fallback>
         <template lwc:if={hasAttributes}>
             <doc-heading
                 header="Attributes"
@@ -66,9 +73,7 @@
                         <template lwc:if={method.firstArgument}>
                             <tr key={method.name}>
                                 <td rowspan={method.arguments.length}>
-                                    <span class="code">
-                                        {method.nameInKebabCase}
-                                    </span>
+                                    <span class="code">{method.name}</span>
                                 </td>
                                 <td rowspan={method.arguments.length}>
                                     {method.description}
@@ -93,9 +98,7 @@
                         <template lwc:else>
                             <tr key={method.name}>
                                 <td>
-                                    <span class="code">
-                                        {method.nameInKebabCase}
-                                    </span>
+                                    <span class="code">{method.name}</span>
                                 </td>
                                 <td>{method.description}</td>
                                 <td colspan="3"></td>

package/src/modules/doc/specificationContent/specificationContent.ts

@@ -10,6 +10,9 @@ export default class SpecificationContent extends LightningElement {
     @api model!: string;
     @api namespace!: string;
 
+    isLoading: boolean = true;
+    showError: boolean = false;
+
     private attributes: Specification[] = [];
     private methods: Method[] = [];
     private slots: Specification[] = [];
@@ -60,7 +63,10 @@ export default class SpecificationContent extends LightningElement {
             }
         } catch (error) {
             this.data = {};
+            this.showError = true;
             console.error("fetchComponentMetadata() failed:", error);
+        } finally {
+            this.isLoading = false;
         }
     }
 

package/src/modules/doc/xmlContent/xmlContent.html

@@ -1,6 +1,6 @@
 <template>
     <doc-content-layout
-        lwc:if={loaded}
+        lwc:if={displayContent}
         lwc:ref="docContentLayout"
         coveo-organization-id={coveoOrganizationId}
         coveo-public-access-token={coveoPublicAccessToken}
@@ -49,4 +49,12 @@
             onnavclick={handleNavClick}
         ></doc-content>
     </doc-content-layout>
+    <div lwc:if={display404}>
+        <dx-error
+            image="https://a.sfdcstatic.com/developer-website/images/404.svg"
+            code="404"
+            header="Beep boop. That did not compute."
+            subtitle="The document you're looking for doesn't seem to exist."
+        ></dx-error>
+    </div>
 </template>

package/src/modules/doc/xmlContent/xmlContent.ts

@@ -11,7 +11,8 @@ import {
     SiderbarFooter,
     HistoryState,
     PageReference,
-    TocMap
+    TocMap,
+    ContentData
 } from "./types";
 import { SearchSyncer } from "docUtils/searchSyncer";
 import { LightningElementWithState } from "dxBaseElements/lightningElementWithState";
@@ -72,7 +73,8 @@ export default class DocXmlContent extends LightningElementWithState<{
     private contentProvider?: FetchContent;
     private docContent = "";
     private language?: DocLanguage | null = null;
-    private loaded = false;
+    private displayContent = false;
+    private display404 = false;
     private _pageHeader?: Header;
     private pdfUrl = "";
     private tocMap: TocMap = {};
@@ -185,7 +187,13 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.apiDomain,
             this.allLanguages
         );
-        this.fetchDocument().then(() => (this.loaded = true));
+        this.fetchDocument().then((content: any) => {
+            if (content) {
+                this.displayContent = true;
+            } else {
+                this.display404 = true;
+            }
+        });
         window.addEventListener("popstate", this.handlePopState);
 
         this.searchSyncer.init();
@@ -463,7 +471,7 @@ export default class DocXmlContent extends LightningElementWithState<{
         );
     }
 
-    async fetchDocument(): Promise<void> {
+    async fetchDocument(): Promise<string> {
         this.setState({
             isFetchingDocument: true
         });
@@ -477,7 +485,7 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.setState({
                 isFetchingDocument: false
             });
-            return;
+            return "";
         }
 
         this.docTitle = data.docTitle;
@@ -509,11 +517,11 @@ export default class DocXmlContent extends LightningElementWithState<{
             data.id
         ) {
             try {
-                await this.fetchContent();
+                const moreData = await this.fetchContent();
                 this.setState({
                     isFetchingDocument: false
                 });
-                return;
+                return moreData.content;
             } catch (error) {
                 this.pageReference.contentDocumentId = `${data.id}.htm`;
                 this.pageReference.hash = "";
@@ -527,9 +535,10 @@ export default class DocXmlContent extends LightningElementWithState<{
         this.setState({
             isFetchingDocument: false
         });
+        return data.content;
     }
 
-    async fetchContent(): Promise<void> {
+    async fetchContent(): Promise<ContentData> {
         this.setState({
             isFetchingContent: true
         });
@@ -553,6 +562,7 @@ export default class DocXmlContent extends LightningElementWithState<{
         this.setState({
             isFetchingContent: false
         });
+        return data;
     }
 
     updateHeaderAndSidebarFooter(): void {