@salesforcedevs/docs-components 0.0.1-edit → 0.0.1-superscript

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

@@ -5,6 +5,7 @@ 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 } };
 
@@ -32,11 +33,6 @@ 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;
@@ -44,10 +40,13 @@ export default class ContentLayout extends LightningElement {
     @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;
@@ -77,6 +76,12 @@ export default class ContentLayout extends LightningElement {
         this._tocOptions = toJson(value);
     }
 
+    /**
+     * The aria-level to filter headings by when building the TOC.
+     * Defaults to "2" (H2 headings).
+     */
+    @api tocAriaLevel: string = "2";
+
     @api
     setSidebarInputValue(searchTerm: string): void {
         (this.template.querySelector("dx-sidebar") as any)?.setInputValue(
@@ -123,6 +128,7 @@ export default class ContentLayout extends LightningElement {
     protected observerTimerId?: NodeJS.Timeout;
     protected didScrollToSelectedHash = false;
     protected _scrollInterval = 0;
+    protected handleLinkClick = buildDocLinkClickHandler();
 
     get showToc(): boolean {
         return this.tocOptions && this.tocOptions.length > 0;
@@ -139,6 +145,10 @@ export default class ContentLayout extends LightningElement {
         );
     }
 
+    get showReadingTime(): boolean {
+        return this.readingTime != null && this.readingTime > 1;
+    }
+
     connectedCallback(): void {
         const hasParentHighlightListener = closest(
             "doc-xml-content",
@@ -151,6 +161,9 @@ export default class ContentLayout extends LightningElement {
             );
             this.searchSyncer.init();
         }
+
+        // Add click handler for all links
+        this.template.addEventListener("click", this.handleLinkClick);
     }
 
     // Placeholder for childs renderedCallback
@@ -192,6 +205,9 @@ export default class ContentLayout extends LightningElement {
         this.clearRenderObserverTimer();
 
         window.clearInterval(this._scrollInterval);
+
+        // Remove link click handler
+        this.template.removeEventListener("click", this.handleLinkClick);
     }
 
     restoreScroll() {
@@ -210,10 +226,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;
@@ -224,15 +237,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.");
@@ -264,39 +282,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`;
             }
         });
     };
@@ -366,19 +399,25 @@ export default class ContentLayout extends LightningElement {
     updateTocItems(headingElements: any): void {
         const tocOptions = [];
 
+        const maxLevel = Number.parseInt(this.tocAriaLevel, 10) || 2;
+        const minLevel = 2;
+
         for (const headingElement of headingElements as any) {
             headingElement.id = headingElement.hash;
 
-            // Update tocOptions from anchorTags only for H2, consider default as 2 as per component
+            // Update tocOptions from anchorTags for aria-levels 2..tocAriaLevel (inclusive)
             const headingAriaLevel =
                 headingElement.attributes["aria-level"]?.nodeValue || "2";
-            const isH2 = headingAriaLevel === "2";
+            const headingLevel = Number.parseInt(headingAriaLevel, 10) || 2;
+            const matchesLevel =
+                headingLevel >= minLevel && headingLevel <= maxLevel;
 
-            if (isH2) {
+            if (matchesLevel) {
                 const tocItem = {
                     anchor: `#${headingElement.hash}`,
                     id: headingElement.id,
-                    label: headingElement.header
+                    label: headingElement.header,
+                    level: headingLevel
                 };
                 tocOptions.push(tocItem);
                 this.tocOptionIdsSet.add(headingElement.id);

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

@@ -8,7 +8,11 @@
                 ></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"

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

@@ -3,6 +3,7 @@ import cx from "classnames";
 import type { OptionWithNested, DevCenterConfig } from "typings/custom";
 import { HeaderBase } from "dxBaseElements/headerBase";
 import { toJson, normalizeBoolean } from "dxUtils/normalizers";
+import { track } from "dxUtils/analytics";
 
 const TABLET_MATCH = "980px";
 const MOBILE_MATCH = "768px";
@@ -117,4 +118,13 @@ export default class Header extends HeaderBase {
             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

@@ -1 +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

@@ -1,58 +1,54 @@
 <template>
     <div class="content">
-        <template lwc:if={useOldSidebar}>
-            <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>
-        </template>
-        <template lwc:else>
-            <dx-sidebar
-                class="is-sticky left-nav-bar"
-                trees={sidebarContent}
-                value={sidebarValue}
-                header={sidebarHeader}
-                coveo-organization-id={coveoOrganizationId}
-                coveo-public-access-token={coveoPublicAccessToken}
-                coveo-search-hub={coveoSearchHub}
-                coveo-advanced-query-config={coveoAdvancedQueryConfig}
-                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>
-        </template>
+        <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">
-            <slot name="doc-phase"></slot>
-            <slot name="version-banner"></slot>
+            <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="content-body">
+                <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="right-nav-bar is-sticky">
+                <div lwc:if={showToc} class={rightNavBarClasses}>
                     <dx-toc
                         header={tocTitle}
                         options={tocOptions}

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

@@ -1,45 +1,125 @@
 import ContentLayout from "doc/contentLayout";
+import cx from "classnames";
 
 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;
     }
 
+    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();
-        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 +145,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 +182,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 +255,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/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>