@salesforcedevs/docs-components 0.7.59-sppage-alpha1 → 0.7.76-alpha

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

@@ -1,16 +1,33 @@
 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";
+import { track } from "dxUtils/analytics";
 
 const TABLET_MATCH = "980px";
 const MOBILE_MATCH = "768px";
 
+const isStorybook = () => {
+    const { host } = window.location;
+    return (
+        host === "localhost:6006" || /^dsc-comp.*\.herokuapp\.com$/.test(host)
+    );
+};
+
 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;
@@ -21,7 +38,7 @@ export default class Header extends HeaderBase {
     }
 
     @api
-    get devCenter() {
+    get devCenter(): DevCenterConfig {
         return this._devCenter;
     }
 
@@ -34,14 +51,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 {
@@ -53,12 +83,12 @@ 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" ||
-            window.location.host === "localhost:6006" ||
-            window.location.host === "dsc-components.herokuapp.com"
+            isStorybook()
         ) {
             this.shouldRender = true;
         }
@@ -85,7 +115,16 @@ 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"
         );
     }
+
+    private onLinkClick(event: Event): void {
+        track(event.target!, "custEv_linkClick", {
+            click_text: this.devCenter.title,
+            click_url: this.devCenter.link,
+            element_type: "link",
+            content_category: "dev-center"
+        });
+    }
 }

package/src/modules/doc/lwcContentLayout/lwcContentLayout.css

@@ -0,0 +1,9 @@
+@import "docHelpers/contentLayoutStyle";
+
+.fixed-right-nav-bar {
+    width: 180px;
+}
+
+.content-body-no-rnb {
+    max-width: 1220px;
+}

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

@@ -0,0 +1,64 @@
+<template>
+    <div class="content">
+        <dx-sidebar-old
+            class="is-sticky left-nav-bar"
+            trees={sidebarContent}
+            value={sidebarValue}
+            header={sidebarHeader}
+            ontogglesidebar={onToggleSidebar}
+            languages={languages}
+            language={language}
+            bail-href={bailHref}
+            bail-label={bailLabel}
+            dev-center={devCenter}
+            brand={brand}
+        >
+            <slot name="sidebar-header" slot="version-picker"></slot>
+        </dx-sidebar-old>
+        <div class="content-body-doc-phase-container">
+            <div class="doc-phase-wrapper">
+                <slot name="doc-phase"></slot>
+            </div>
+            <div class="version-wrapper">
+                <slot name="version-banner"></slot>
+            </div>
+            <div class="content-body-container">
+                <div class={contentBodyClasses}>
+                    <doc-breadcrumbs
+                        lwc:if={showBreadcrumbs}
+                        breadcrumbs={breadcrumbs}
+                    ></doc-breadcrumbs>
+                    <div class="read" lwc:if={showReadingTime}>
+                        <svg
+                            xmlns="http://www.w3.org/2000/svg"
+                            width="18"
+                            height="18"
+                            viewBox="0 0 52 52"
+                        >
+                            <g fill="#3e3e3c">
+                                <path
+                                    d="m26 2c-13.2 0-24 10.8-24 24s10.8 24 24 24 24-10.8 24-24-10.8-24-24-24z m0 42c-9.9 0-18-8.1-18-18s8.1-18 18-18 18 8.1 18 18-8.1 18-18 18z m3.4-17.8c-0.3-0.3-0.4-0.7-0.4-1.1v-9.6c0-0.8-0.7-1.5-1.5-1.5h-3c-0.8 0-1.5 0.7-1.5 1.5v12.1c0 0.4 0.2 0.8 0.4 1.1l7.4 7.4c0.6 0.6 1.5 0.6 2.1 0l2.1-2.1c0.6-0.6 0.6-1.5 0-2.1l-5.6-5.7z"
+                                ></path>
+                            </g>
+                        </svg>
+                        {readingTime} minute read
+                    </div>
+                    <slot onslotchange={onSlotChange}></slot>
+                    <doc-sprig-survey
+                        lwc:if={shouldDisplayFeedback}
+                    ></doc-sprig-survey>
+                </div>
+                <div lwc:if={showToc} class={rightNavBarClasses}>
+                    <dx-toc
+                        header={tocTitle}
+                        options={tocOptions}
+                        value={tocValue}
+                    ></dx-toc>
+                </div>
+            </div>
+            <div lwc:if={showFooter} class="footer-container">
+                <dx-footer variant="no-signup"></dx-footer>
+            </div>
+        </div>
+    </div>
+</template>

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

@@ -0,0 +1,269 @@
+import ContentLayout from "doc/contentLayout";
+import cx from "classnames";
+
+const TOC_HEADER_TAG = "doc-heading";
+const RNB_BY_TAB = "docs-tab";
+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 = this.getTabPanelList();
+        this.rnbByTab = tabPanelListItem?.id === RNB_BY_TAB;
+    }
+
+    get showTabBasedRNB() {
+        return this.rnbByTab;
+    }
+
+    get rightNavBarClasses() {
+        return cx(
+            "right-nav-bar",
+            "is-sticky",
+            this.showTabBasedRNB && "fixed-right-nav-bar"
+        );
+    }
+
+    get contentBodyClasses() {
+        return cx("content-body", !this.showToc && "content-body-no-rnb");
+    }
+
+    /**
+     * 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();
+        if (this.hasSpecificationContent()) {
+            this.didScrollToSelectedHash = false;
+        }
+    };
+
+    onTabChanged = () => {
+        this.updateRNB();
+
+        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 = this.getTabPanelList();
+            const tabPanels =
+                tabPanelListItem?.querySelectorAll("dx-tab-panel");
+
+            for (const tabPanelItem of tabPanels) {
+                if (tabPanelItem.active) {
+                    // This is needed for Specification tab content
+                    const specificationElement = tabPanelItem.querySelector(
+                        "doc-specification-content"
+                    );
+                    if (specificationElement) {
+                        headingElements =
+                            specificationElement.shadowRoot.querySelectorAll(
+                                TOC_HEADER_TAG
+                            );
+                    } else {
+                        headingElements =
+                            tabPanelItem.querySelectorAll(TOC_HEADER_TAG);
+                    }
+                    break;
+                }
+            }
+        }
+        return headingElements;
+    }
+
+    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");
+                const url = new URL(window.location.href);
+                if (selectedTabId !== tabID) {
+                    url.searchParams.set("type", tabID);
+                    url.hash = "";
+                    window.history.pushState({}, "", url.toString());
+                }
+            }
+        });
+    }
+
+    // This event gets triggered when navigating back/forward
+    handlePopState = (): void => {
+        if (this.showTabBasedRNB) {
+            this.restoreTabSelection();
+        }
+    };
+
+    connectedCallback(): void {
+        super.connectedCallback();
+        window.addEventListener("popstate", this.handlePopState);
+    }
+
+    private getSelectedTabId() {
+        const urlParams = new URLSearchParams(window.location.search);
+        const selectedTabId = urlParams.get("type");
+        return selectedTabId;
+    }
+
+    private restoreTabSelection() {
+        requestAnimationFrame(() => {
+            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[] {
+        // Return cached result if available
+        if (this.allTabsCache) {
+            return this.allTabsCache;
+        }
+
+        const tabPanelListItem = this.getTabPanelList();
+        if (tabPanelListItem?.shadowRoot) {
+            this.allTabsCache = Array.from(
+                tabPanelListItem.shadowRoot.querySelectorAll(
+                    "dx-tab-panel-item"
+                )
+            ).map((tabPanelItem: any) =>
+                tabPanelItem.shadowRoot.querySelector("button")
+            );
+        } else {
+            this.allTabsCache = [];
+        }
+
+        return this.allTabsCache;
+    }
+
+    private selectTabById(tabId: string) {
+        const tabs = this.getAllTabs();
+        tabs.forEach((tab: any) => {
+            if (tab.getAttribute("aria-label") === tabId) {
+                tab.click();
+            }
+        });
+    }
+
+    postRenderedCallback(): void {
+        this.setRNBByTab();
+        if (this.showTabBasedRNB) {
+            window.addEventListener("tabchanged", this.onTabChanged);
+            window.addEventListener(
+                "specificationdatarendered",
+                this.onTabChanged
+            );
+            window.addEventListener("selectedcontent", (event) =>
+                this.onRNBClick(event as CustomEvent)
+            );
+            this.restoreTabSelection();
+        }
+    }
+
+    disconnectedCallback(): void {
+        super.disconnectedCallback();
+        if (this.showTabBasedRNB) {
+            window.removeEventListener("tabchanged", this.onTabChanged);
+            window.removeEventListener(
+                "specificationdatarendered",
+                this.onTabChanged
+            );
+            window.removeEventListener("selectedcontent", (event) =>
+                this.onRNBClick(event as CustomEvent)
+            );
+            window.removeEventListener("popstate", this.handlePopState);
+        }
+    }
+
+    onSlotChange(): void {
+        this.clearAllCaches();
+        super.onSlotChange();
+    }
+
+    updateHeadingForRNB(): void {
+        if (this.showTabBasedRNB) {
+            this.updateURL();
+        }
+        super.updateHeadingForRNB();
+    }
+}

package/src/modules/doc/phase/phase.css

@@ -3,14 +3,7 @@
 @import "docHelpers/status";
 
 :host {
-    --doc-c-phase-top: 0;
     --doc-c-phase-container-align-items: flex-start;
-
-    position: sticky;
-    top: var(--doc-c-phase-top);
-
-    /* NOTE: If you are changing z-index value here, ensure it's less than z-index of dx-sidebar in contentLayout.css */
-    z-index: var(--dx-g-z-index-100);
 }
 
 .doc-phase-container {

package/src/modules/doc/redocReference/redocReference.css

@@ -0,0 +1,7 @@
+:host {
+    --dx-footer-margin-top: 142px;
+    --doc-c-redoc-sidebar-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+            var(--dx-g-spacing-xl)
+    );
+}

package/src/modules/doc/redocReference/redocReference.html

@@ -0,0 +1,13 @@
+<template>
+    <template lwc:if={showError}>
+        <dx-error
+            header="We lost communication with the space station."
+            subtitle="We encountered a server-related issue. (Don't worry, we're on it.) Refresh your browser or try again later."
+            image=""
+            code="500"
+        ></dx-error>
+    </template>
+    <template lwc:else>
+        <slot></slot>
+    </template>
+</template>