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

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

@@ -5,13 +5,14 @@ import { toJson } from "dxUtils/normalizers";
 import { highlightTerms } from "dxUtils/highlight";
 import { SearchSyncer } from "docUtils/searchSyncer";
 import type { OptionWithLink } from "typings/custom";
+import { buildDocLinkClickHandler } from "dxUtils/analytics";
 
 type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
 
 declare const Sprig: (eventType: string, eventNme: string) => void;
 
 const TOC_HEADER_TAG = "doc-heading";
-const RNB_BY_TAB = "docs-tab";
+
 const HIGHLIGHTABLE_SELECTOR = [
     "p",
     "h1",
@@ -32,20 +33,20 @@ export default class ContentLayout extends LightningElement {
     @api sidebarHeader!: string;
     @api tocTitle!: string;
     @api enableSlotChange = false;
-    @api coveoOrganizationId!: string;
-    @api coveoPublicAccessToken!: string;
-    @api coveoAnalyticsToken!: string;
-    @api coveoSearchHub!: string;
-    @api coveoAdvancedQueryConfig!: string;
     @api useOldSidebar?: boolean = false;
     @api languages!: OptionWithLink[];
     @api language!: string;
     @api bailHref!: string;
     @api bailLabel!: string;
+    @api devCenter: any;
+    @api brand: any;
+    @api emptyStateMessage?: string;
 
     // This is needed for now to prevent failing snapshot tests due to links in the footer
     @api showFooter = false;
 
+    @api readingTime?: number;
+
     @api
     get breadcrumbs() {
         return this._breadcrumbs;
@@ -83,87 +84,26 @@ export default class ContentLayout extends LightningElement {
     }
 
     @track
-    private _sidebarContent: unknown;
+    protected _sidebarContent: unknown;
 
-    private _breadcrumbs = null;
+    protected _breadcrumbs = null;
 
     @track
-    private _tocOptions!: Array<unknown>;
+    protected _tocOptions!: Array<unknown>;
 
-    private tocOptionIdsSet = new Set();
-    private anchoredElements: AnchorMap = {};
-    private lastScrollPosition!: number;
-    private observer?: IntersectionObserver;
-    private hasRendered: boolean = false;
-    private contentLoaded: boolean = false;
-    private sidebarOpen: boolean = false;
-    private rnbByTab: boolean = false;
+    protected tocOptionIdsSet = new Set();
+    protected anchoredElements: AnchorMap = {};
+    protected lastScrollPosition!: number;
+    protected observer?: IntersectionObserver;
+    protected hasRendered: boolean = false;
+    protected contentLoaded: boolean = false;
+    protected sidebarOpen: boolean = false;
 
     get shouldDisplayFeedback() {
         return this.contentLoaded && typeof Sprig !== "undefined";
     }
 
-    private setRNBByTab() {
-        const tabPanelListItem: any = this.getTabPanelList();
-        this.rnbByTab = tabPanelListItem?.id === RNB_BY_TAB ? true : false;
-    }
-
-    get showTabBasedRNB() {
-        return this.rnbByTab;
-    }
-
-    onTabChanged = () => {
-        this.updateRNB();
-    };
-
-    private getTabPanelList() {
-        return document.querySelector("dx-tab-panel-list");
-    }
-
-    updateRNB = () => {
-        const headingElements = this.getHeadingElements();
-        headingElements.forEach((headingElement: any) => {
-            // Sometimes elements hash and header is not being set when slot content is wrapped with div
-            headingElement.hash = headingElement.attributes.hash?.nodeValue;
-            headingElement.header = headingElement.attributes.header?.nodeValue;
-        });
-        this.updateTocItems(headingElements);
-    };
-
-    private getHeadingElements() {
-        let headingElements = document.querySelectorAll(TOC_HEADER_TAG);
-        if (this.showTabBasedRNB) {
-            const tabPanelListItem: any = this.getTabPanelList();
-            const tabPanels =
-                tabPanelListItem?.querySelectorAll("dx-tab-panel");
-            for (const tabPanelItem of tabPanels) {
-                if (tabPanelItem.active) {
-                    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());
-                }
-            }
-        });
-    }
-
-    private searchSyncer = new SearchSyncer({
+    protected searchSyncer = new SearchSyncer({
         callbacks: {
             onSearchChange: (nextSearchString: string): void => {
                 this.dispatchHighlightChange(
@@ -177,11 +117,12 @@ export default class ContentLayout extends LightningElement {
         shouldStopPropagation: true,
         target: window
     });
-    private tocValue?: string = undefined;
+    protected tocValue?: string = undefined;
     // eslint-disable-next-line no-undef
-    private observerTimerId?: NodeJS.Timeout;
-    private didScrollToSelectedHash = false;
-    private _scrollInterval = 0;
+    protected observerTimerId?: NodeJS.Timeout;
+    protected didScrollToSelectedHash = false;
+    protected _scrollInterval = 0;
+    protected handleLinkClick = buildDocLinkClickHandler();
 
     get showToc(): boolean {
         return this.tocOptions && this.tocOptions.length > 0;
@@ -198,12 +139,9 @@ export default class ContentLayout extends LightningElement {
         );
     }
 
-    // This event gets triggered when navigating back/forward
-    handlePopState = (): void => {
-        if (this.showTabBasedRNB) {
-            this.restoreTabSelection();
-        }
-    };
+    get showReadingTime(): boolean {
+        return this.readingTime != null && this.readingTime > 0;
+    }
 
     connectedCallback(): void {
         const hasParentHighlightListener = closest(
@@ -217,46 +155,13 @@ export default class ContentLayout extends LightningElement {
             );
             this.searchSyncer.init();
         }
-        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);
-            }
-        });
-    }
 
-    private getAllTabs(): any[] {
-        const tabPanelListItem: any = this.getTabPanelList();
-        if (tabPanelListItem?.shadowRoot) {
-            return Array.from(
-                tabPanelListItem.shadowRoot.querySelectorAll(
-                    "dx-tab-panel-item"
-                )
-            ).map((tabPanelItem: any) =>
-                tabPanelItem.shadowRoot.querySelector("button")
-            );
-        }
-        return [];
+        // Add click handler for all links
+        this.template.addEventListener("click", this.handleLinkClick);
     }
 
-    private selectTabById(tabId: string) {
-        const tabs = this.getAllTabs();
-        tabs.forEach((tab: any) => {
-            if (tab.getAttribute("aria-label") === tabId) {
-                tab.click();
-            }
-        });
-    }
+    // Placeholder for childs renderedCallback
+    protected postRenderedCallback?(): void;
 
     renderedCallback(): void {
         /**
@@ -275,12 +180,10 @@ export default class ContentLayout extends LightningElement {
 
         if (!this.hasRendered) {
             this.hasRendered = true;
-            this.setRNBByTab();
-            if (this.showTabBasedRNB) {
-                window.addEventListener("tabchanged", this.onTabChanged);
-                this.restoreTabSelection();
-            }
             this.restoreScroll();
+
+            // Dynamically call `renderedCallbackForLwcContentLayout` if it exists
+            this.postRenderedCallback?.();
         }
     }
 
@@ -292,12 +195,13 @@ export default class ContentLayout extends LightningElement {
         );
         window.removeEventListener("scroll", this.adjustNavPosition);
         window.removeEventListener("resize", this.adjustNavPosition);
-        window.removeEventListener("tabchanged", this.onTabChanged);
-        window.removeEventListener("popstate", this.handlePopState);
         this.searchSyncer.dispose();
         this.clearRenderObserverTimer();
 
         window.clearInterval(this._scrollInterval);
+
+        // Remove link click handler
+        this.template.removeEventListener("click", this.handleLinkClick);
     }
 
     restoreScroll() {
@@ -316,10 +220,7 @@ export default class ContentLayout extends LightningElement {
         We have to account for the global nav changing height due to animations.
     */
     adjustNavPosition = () => {
-        const sidebarType = this.useOldSidebar
-            ? "dx-sidebar-old"
-            : "dx-sidebar";
-        const sidebarEl = this.template.querySelector(sidebarType);
+        const sidebarEl = this.template.querySelector("dx-sidebar-old");
         const globalNavEl = document.querySelector(
             "hgf-c360nav"
         ) as HTMLElement;
@@ -330,15 +231,20 @@ export default class ContentLayout extends LightningElement {
             ".sticky-doc-header"
         ) as HTMLElement;
 
-        let docPhaseEl = (
-            this.template.querySelector("[name=doc-phase]")! as any
+        const docPhaseWrapper = this.template.querySelector(
+            ".doc-phase-wrapper"
+        ) as HTMLElement;
+        const versionWrapper = this.template.querySelector(
+            ".version-wrapper"
+        ) as HTMLElement;
+
+        const docPhaseEl = (
+            docPhaseWrapper.querySelector("[name=doc-phase]")! as any
         ).assignedElements()[0] as HTMLSlotElement;
 
-        if (!docPhaseEl) {
-            docPhaseEl = (
-                this.template.querySelector("[name=version-banner]")! as any
-            ).assignedElements()[0] as HTMLSlotElement;
-        }
+        const verBannerEl = (
+            versionWrapper.querySelector("[name=version-banner]")! as any
+        ).assignedElements()[0] as HTMLSlotElement;
 
         if (!sidebarEl || !globalNavEl || !contextNavEl || !docHeaderEl) {
             console.warn("One or more required elements are missing.");
@@ -370,39 +276,54 @@ export default class ContentLayout extends LightningElement {
                 `${globalNavHeight}px`
             );
 
+            const docPhaseElHeight =
+                docPhaseEl || verBannerEl
+                    ? (docPhaseEl || verBannerEl).getBoundingClientRect().height
+                    : 0;
+
             // Adjusting the doc section heading on scroll.
             docHeadingEls.forEach((docHeadingEl) => {
-                (docHeadingEl as any).style.scrollMarginTop = docPhaseEl
-                    ? `${
-                          totalHeaderHeight +
-                          docPhaseEl.getBoundingClientRect().height +
-                          40
-                      }px`
-                    : `${totalHeaderHeight + 40}px`;
+                (docHeadingEl as any).style.scrollMarginTop = `${
+                    totalHeaderHeight + docPhaseElHeight + 40
+                }px`;
             });
 
             // Adjusting the right nav bar on scroll.
+            // setting maxheight to make the RNB scrollable based on different parent elements
             if (rightNavBarEl) {
-                rightNavBarEl.style.top = docPhaseEl
-                    ? `${
-                          totalHeaderHeight +
-                          docPhaseEl.getBoundingClientRect().height
-                      }px`
-                    : `${totalHeaderHeight}px`;
+                const viewportHeight = window.innerHeight;
+                const maxHeight =
+                    viewportHeight -
+                    (docPhaseElHeight + totalHeaderHeight + 24); //added some margin of dx-toc
+
+                rightNavBarEl.style.top = `${
+                    totalHeaderHeight + docPhaseElHeight
+                }px`;
+
+                const toc = rightNavBarEl.querySelector("dx-toc");
+                const listContainer = toc?.shadowRoot?.querySelector(
+                    ".toc"
+                ) as HTMLElement;
+
+                if (listContainer) {
+                    listContainer.style.maxHeight = `${maxHeight}px`;
+                }
             }
 
+            const docPhaseTop =
+                window.innerWidth < 769
+                    ? globalNavHeight +
+                      docHeaderHeight +
+                      sidebarEl.getBoundingClientRect().height
+                    : globalNavHeight + docHeaderHeight;
+
             // If doc phase element exists, we need to account for its sticky position. Mobile should include the sidebar height (since it becomes sticky aswell).
+            // To handle sticky position for safari browser, position sticky given to wrapper class
             if (docPhaseEl) {
-                docPhaseEl.style.setProperty(
-                    "--doc-c-phase-top",
-                    `${
-                        window.innerWidth < 769
-                            ? globalNavHeight +
-                              docHeaderHeight +
-                              sidebarEl.getBoundingClientRect().height
-                            : globalNavHeight + docHeaderHeight
-                    }px`
-                );
+                docPhaseWrapper.style.top = `${docPhaseTop}px`;
+            } else if (verBannerEl) {
+                versionWrapper.style.position = "sticky";
+                versionWrapper.style.top = `${docPhaseTop}px`;
             }
         });
     };
@@ -413,6 +334,34 @@ export default class ContentLayout extends LightningElement {
             (event as CustomEvent<string>).detail
         );
 
+    protected getHeadingElements() {
+        // Note: We are doing document.querySelectorAll as a quick fix as we are not getting heading elements reference this.querySelectorAll
+        const headingElements = document.querySelectorAll(TOC_HEADER_TAG);
+        return headingElements;
+    }
+
+    updateHeadingForRNB(): void {
+        const headingElements = this.getHeadingElements();
+        this.addObserverAndScroll(headingElements);
+    }
+
+    addObserverAndScroll(headingElements: any) {
+        for (const headingElement of headingElements as any) {
+            // Add headingElements to intersectionObserver for highlighting respective RNB item when user scroll
+            const id = headingElement.getAttribute("id")!;
+            this.anchoredElements[id] = {
+                id,
+                intersect: false
+            };
+            this.observer?.observe(headingElement);
+        }
+
+        if (!this.didScrollToSelectedHash) {
+            this.didScrollToSelectedHash = true;
+            this.scrollToHash(headingElements);
+        }
+    }
+
     attachInteractionObserver = (): void => {
         if (!this.enableSlotChange) {
             return;
@@ -437,38 +386,11 @@ export default class ContentLayout extends LightningElement {
                 rootMargin: globalNavOffset.trim()
             }
         );
-
-        // Note: We are doing document.querySelectorAll as a quick fix as we are not getting heading elements reference this.querySelectorAll
-        const headingElements = this.getHeadingElements();
-
-        // 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();
-        }
-
-        for (const headingElement of headingElements as any) {
-            // Add headingElements to intersectionObserver for highlighting respective RNB item when user scroll
-            const id = headingElement.getAttribute("id")!;
-            this.anchoredElements[id] = {
-                id,
-                intersect: false
-            };
-            this.observer.observe(headingElement);
-        }
-
-        if (!this.didScrollToSelectedHash) {
-            this.didScrollToSelectedHash = true;
-            this.scrollToHash(headingElements);
-        }
+        this.updateHeadingForRNB();
     };
 
-    onSlotChange(): void {
-        this.updateRNB();
-        this.contentLoaded = true;
-    }
-
     // eslint-disable-next-line no-undef
-    private updateTocItems(headingElements: NodeListOf<Element>): void {
+    updateTocItems(headingElements: any): void {
         const tocOptions = [];
 
         for (const headingElement of headingElements as any) {
@@ -493,7 +415,33 @@ export default class ContentLayout extends LightningElement {
         this._tocOptions = tocOptions;
     }
 
-    private disconnectObserver(): void {
+    setHashAndHeaderForDocHeading(headingElements: any) {
+        for (const headingElement of headingElements as any) {
+            // Sometimes elements hash and header is not being set when slot content is wrapped with div
+            if (!headingElement.hash) {
+                headingElement.hash = headingElement.attributes.hash?.nodeValue;
+            }
+
+            if (!headingElement.header) {
+                headingElement.header =
+                    headingElement.attributes.header?.nodeValue;
+            }
+        }
+
+        this.updateTocItems(headingElements);
+    }
+
+    updateRNB = () => {
+        const headingElements = this.getHeadingElements();
+        this.setHashAndHeaderForDocHeading(headingElements);
+    };
+
+    onSlotChange(): void {
+        this.updateRNB();
+        this.contentLoaded = true;
+    }
+
+    protected disconnectObserver(): void {
         if (this.observer) {
             this.observer.disconnect();
             this.observer = undefined;
@@ -501,7 +449,7 @@ export default class ContentLayout extends LightningElement {
     }
 
     // eslint-disable-next-line no-undef
-    private scrollToHash(headingElements: NodeListOf<Element>): void {
+    protected scrollToHash(headingElements: NodeListOf<Element>): void {
         let { hash } = window.location;
         if (hash) {
             hash = hash.substr(1);
@@ -538,7 +486,7 @@ export default class ContentLayout extends LightningElement {
         }
     }
 
-    private scrollIntoViewWithOffset(
+    protected scrollIntoViewWithOffset(
         headingElement: HTMLElement,
         offset: number
     ) {
@@ -551,7 +499,7 @@ export default class ContentLayout extends LightningElement {
         });
     }
 
-    private calculateActualSection(): void {
+    protected calculateActualSection(): void {
         const currentScrollPosition = document.documentElement.scrollTop;
         const id = Object.keys(this.anchoredElements).find(
             (_id) => this.anchoredElements[_id].intersect
@@ -566,21 +514,21 @@ export default class ContentLayout extends LightningElement {
         this.lastScrollPosition = currentScrollPosition;
     }
 
-    private calculatePreviousElementId(): string | undefined {
+    protected calculatePreviousElementId(): string | undefined {
         const keys = Object.keys(this.anchoredElements);
         const currentIndex = keys.findIndex((id) => this.tocValue === id);
 
         return currentIndex > 0 ? keys[currentIndex - 1] : undefined;
     }
 
-    private assignElementId(id: string | undefined): void {
+    protected assignElementId(id: string | undefined): void {
         // Change toc(RNB) highlight only for H2
         if (this.tocOptionIdsSet.has(id)) {
             this.tocValue = id;
         }
     }
 
-    private dispatchHighlightChange(term: string): void {
+    protected dispatchHighlightChange(term: string): void {
         this.dispatchEvent(
             new CustomEvent("highlightedtermchange", {
                 detail: term,
@@ -590,14 +538,14 @@ export default class ContentLayout extends LightningElement {
         );
     }
 
-    private updateHighlightsAndSearch(nextSearchString: string): void {
+    protected updateHighlightsAndSearch(nextSearchString: string): void {
         const nextSearchParam =
             new URLSearchParams(nextSearchString).get("q") || "";
         this.setSidebarInputValue(nextSearchParam);
         this.dispatchHighlightChange(nextSearchParam);
     }
 
-    private onToggleSidebar(e: CustomEvent): void {
+    protected onToggleSidebar(e: CustomEvent): void {
         this.sidebarOpen = e.detail.open;
 
         // eslint-disable-next-line @lwc/lwc/no-document-query

package/src/modules/doc/contentMedia/contentMedia.css

@@ -29,7 +29,7 @@
 
 .content-media-iframe {
     position: relative;
-    padding-bottom: calc(var(--aspect-ratio, 0.5625) * 100%);
+    padding-bottom: calc(var(--aspect-ratio, 0.5626) * 100%);
     height: 0;
 }
 

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

@@ -6,8 +6,13 @@
                     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">
+                    <a
+                        href={devCenter.link}
+                        onclick={onLinkClick}
+                        class="dev-center-content"
+                    >
                         <dx-icon symbol="back"></dx-icon>
                         <dx-icon
                             class="brand-icon"
@@ -30,7 +35,7 @@
                         </a>
                     </div>
                     <div
-                        lwc:if={hasScopedNavItems}
+                        lwc:if={showScopedNavItems}
                         class="header_l2_group header_l2_group-nav"
                     >
                         <div
@@ -48,7 +53,7 @@
             </header>
         </dx-brand-theme-provider>
     </template>
-    <template lwc:if={showDocDivider}>
+    <template lwc:if={shouldHideHeader}>
         <div class="no-header-content"></div>
     </template>
 </template>