@salesforcedevs/docs-components 1.3.130 → 1.3.138

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.3.130",
+    "version": "1.3.138",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
@@ -24,5 +24,5 @@
         "@types/lodash.orderby": "^4.6.7",
         "@types/lodash.uniqby": "^4.7.7"
     },
-    "gitHead": "cd52db111aee7bb881d15862490c5c07463acb3b"
+    "gitHead": "23c5aa9a539b956d4d2c592d366663510af4f2ac"
 }

package/src/modules/doc/amfReference/amfReference.css

@@ -4,6 +4,21 @@ doc-phase {
     );
 }
 
+/* We need to apply some borders when there are two doc phases */
+doc-phase:not(:only-of-type)::part(container) {
+    border-top: 1px solid var(--dx-g-yellow-vibrant-90);
+}
+
+doc-phase:nth-child(2)::part(container) {
+    border-top: 1px solid var(--dx-g-yellow-vibrant-90);
+    border-bottom: 1px solid var(--dx-g-yellow-vibrant-90);
+}
+
+/* We don't want second component to sticky as we need to handle different cases like position */
+doc-phase:nth-child(2) {
+    position: static;
+}
+
 .api-documentation {
     margin-top: 48px;
 }

package/src/modules/doc/amfReference/amfReference.html

@@ -21,6 +21,14 @@
             if:true={docPhaseInfo}
             doc-phase-info={docPhaseInfo}
         ></doc-phase>
+        <doc-phase
+            slot="version-banner"
+            if:true={showVersionBanner}
+            doc-phase-info={oldVersionInfo}
+            icon-name="warning"
+            dismissible="true"
+            ondismissphase={handleDismissVersionBanner}
+        ></doc-phase>
         <div slot="sidebar-header" class="version-picker">
             <template if:true={isVersionEnabled}>
                 <dx-dropdown

package/src/modules/doc/amfReference/amfReference.ts

@@ -26,6 +26,8 @@ import {
     oldReferenceIdNewReferenceIdMap
 } from "./constants";
 import { restoreScroll } from "dx/scrollManager";
+import { DocPhaseInfo } from "typings/custom";
+import { oldVersionDocInfo } from "docUtils/utils";
 
 export default class AmfReference extends LightningElement {
     @api breadcrumbs?: string | null | undefined = null;
@@ -39,6 +41,7 @@ export default class AmfReference extends LightningElement {
     @api tocOptions?: string;
     @track navigation = [];
     @track versions: Array<ReferenceVersion> = [];
+    @track showVersionBanner = false;
 
     // Update this to update what component gets rendered in the content block
     @track
@@ -102,6 +105,12 @@ export default class AmfReference extends LightningElement {
                 this.versions = this.getVersions();
             }
             this.selectedVersion = selectedVersion;
+            if (
+                this.isSpecBasedReference(this._currentReferenceId) &&
+                this.oldVersionInfo
+            ) {
+                this.showVersionBanner = true;
+            }
         }
 
         // This is to check if the url is hash based and redirect if needed
@@ -167,12 +176,10 @@ export default class AmfReference extends LightningElement {
     constructor() {
         super();
 
-        this._boundOnApiNavigationChanged = this.onApiNavigationChanged.bind(
-            this
-        );
-        this._boundUpdateSelectedItemFromUrlQuery = this.updateSelectedItemFromUrlQuery.bind(
-            this
-        );
+        this._boundOnApiNavigationChanged =
+            this.onApiNavigationChanged.bind(this);
+        this._boundUpdateSelectedItemFromUrlQuery =
+            this.updateSelectedItemFromUrlQuery.bind(this);
     }
 
     connectedCallback(): void {
@@ -228,9 +235,8 @@ export default class AmfReference extends LightningElement {
                 const updatedReferenceId =
                     oldReferenceIdNewReferenceIdMap[referenceId];
                 const newReferenceId = updatedReferenceId || referenceId;
-                const referenceItemConfig = this.getAmfConfigWithId(
-                    newReferenceId
-                );
+                const referenceItemConfig =
+                    this.getAmfConfigWithId(newReferenceId);
                 if (referenceItemConfig) {
                     hashBasedRedirectUrl = `${referenceItemConfig.href}?meta=${encodedMeta}`;
                 }
@@ -285,6 +291,17 @@ export default class AmfReference extends LightningElement {
         return referenceId;
     }
 
+    private get oldVersionInfo(): DocPhaseInfo | null {
+        let info = null;
+        if (this.versions.length > 1 && this.selectedVersion) {
+            const currentGAVersionRef = this.versions[0];
+            if (this.selectedVersion.id !== currentGAVersionRef.id) {
+                info = oldVersionDocInfo(currentGAVersionRef.link.href);
+            }
+        }
+        return info;
+    }
+
     /**
      * @returns versions to be shown in the dropdown
      * For markdown based specs, Adds selected markdown topic url to same references
@@ -299,9 +316,8 @@ export default class AmfReference extends LightningElement {
                 for (let i = 0; i < allVersions.length; i++) {
                     const versionItem = allVersions[i];
                     const referenceLink = versionItem.link.href;
-                    const referenceId = this.getReferenceIdFromUrl(
-                        referenceLink
-                    );
+                    const referenceId =
+                        this.getReferenceIdFromUrl(referenceLink);
                     if (this._currentReferenceId === referenceId) {
                         // This is to navigate to respective topic in the changed version
                         versionItem.link.href = `${referenceLink}/${currentRefMeta}`;
@@ -1226,12 +1242,10 @@ export default class AmfReference extends LightningElement {
         }
         if (!isRedirecting) {
             const currentReferenceUrl = window.location.href;
-            const referenceMeta = this.getMarkdownReferenceMeta(
-                currentReferenceUrl
-            );
-            const selectedItemRefId = this.getReferenceIdFromUrl(
-                currentReferenceUrl
-            );
+            const referenceMeta =
+                this.getMarkdownReferenceMeta(currentReferenceUrl);
+            const selectedItemRefId =
+                this.getReferenceIdFromUrl(currentReferenceUrl);
             const referenceDetails = this.getRefDetailsForGivenTopicMeta(
                 selectedItemRefId,
                 referenceMeta
@@ -1241,6 +1255,9 @@ export default class AmfReference extends LightningElement {
             }
 
             this.versions = this.getVersions();
+            if (this.oldVersionInfo) {
+                this.showVersionBanner = true;
+            }
             this.updateDocPhase();
             this.selectedSidebarValue = window.location.pathname;
         }
@@ -1257,6 +1274,10 @@ export default class AmfReference extends LightningElement {
         );
     }
 
+    handleDismissVersionBanner() {
+        this.showVersionBanner = false;
+    }
+
     private updateNavTitleMetaTag(navTitle = ""): void {
         // this is required to update the nav title meta tag.
         // eslint-disable-next-line @lwc/lwc/no-document-query
@@ -1270,9 +1291,8 @@ export default class AmfReference extends LightningElement {
         const name = event.detail.name;
         if (name) {
             const urlReferenceId = this.getReferenceIdFromUrl(name);
-            const specBasedReference = this.isSpecBasedReference(
-                urlReferenceId
-            );
+            const specBasedReference =
+                this.isSpecBasedReference(urlReferenceId);
             if (specBasedReference) {
                 const metaVal = this.getMetaFromUrl(name);
                 const currentSelectedMeta = this.selectedTopic
@@ -1322,9 +1342,8 @@ export default class AmfReference extends LightningElement {
             const currentReferenceId = this.getReferenceIdFromUrl(currentUrl);
             //No need to do anything if user is expanding currently selected reference
             if (referenceId !== currentReferenceId) {
-                const isSpecBasedReference = this.isSpecBasedReference(
-                    referenceId
-                );
+                const isSpecBasedReference =
+                    this.isSpecBasedReference(referenceId);
                 if (isSpecBasedReference) {
                     // Perform functionality same as item selection
                     this.onNavSelect(event);

package/src/modules/doc/amfReference/types.ts

@@ -1,4 +1,4 @@
-import { Json } from "typings/custom";
+import { Json, DocPhaseInfo } from "typings/custom";
 
 export interface AmfTopicType {
     referenceId: string;
@@ -46,14 +46,6 @@ export interface AmfModelRecord {
     parsedModel: Json;
 }
 
-export type DocPhase = "pilot" | "dev-preview" | "beta";
-
-export type DocPhaseEntry = {
-    phase: DocPhase;
-    title: string;
-    body: string;
-};
-
 export type ReferenceType = "markdown" | "rest-raml" | "rest-oa2" | "rest-oa3";
 
 /**
@@ -73,7 +65,7 @@ export interface ParsedMarkdownTopic {
 export interface AmfConfig {
     id: string;
     version?: string;
-    docPhase?: DocPhaseEntry;
+    docPhase?: DocPhaseInfo;
     title: string;
     href: string;
     referenceType: ReferenceType;

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

@@ -28,6 +28,7 @@
         </template>
         <div class="content-body-doc-phase-container">
             <slot name="doc-phase"></slot>
+            <slot name="version-banner"></slot>
             <div class="content-body-container">
                 <div class="content-body">
                     <doc-breadcrumbs

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

@@ -92,9 +92,6 @@ export default class ContentLayout extends LightningElement {
 
     private searchSyncer = new SearchSyncer({
         callbacks: {
-            onUrlChange: (nextSearchString: string): void => {
-                this.updateHighlightsAndSearch(nextSearchString);
-            },
             onSearchChange: (nextSearchString: string): void => {
                 this.dispatchHighlightChange(
                     new URLSearchParams(nextSearchString).get("q") || ""
@@ -217,13 +214,16 @@ export default class ContentLayout extends LightningElement {
 
         // sync with the browser to account for any reflows that may have happened
         requestAnimationFrame(() => {
+            // ternary is a temporary fix for the global nav height reporting incorrectly on some browsers
             const globalNavHeight =
-                globalNavEl.offsetHeight + contextNavEl.offsetHeight;
-            const docHeaderHeight = docHeaderEl.offsetHeight;
+                (globalNavEl.getBoundingClientRect().height !== 72 ? 0 : 72) +
+                contextNavEl.getBoundingClientRect().height;
+            const docHeaderHeight = docHeaderEl.getBoundingClientRect().height;
             sidebarEl.style.setProperty(
                 "--dx-c-content-sidebar-sticky-top",
                 `${globalNavHeight + docHeaderHeight}px`
             );
+
             docHeaderEl.style.setProperty(
                 "--dx-g-global-header-height",
                 `${globalNavHeight}px`
@@ -237,7 +237,7 @@ export default class ContentLayout extends LightningElement {
                         window.innerWidth < 769
                             ? globalNavHeight +
                               docHeaderHeight +
-                              sidebarEl.offsetHeight
+                              sidebarEl.getBoundingClientRect().height
                             : globalNavHeight + docHeaderHeight
                     }px`
                 );
@@ -250,7 +250,7 @@ export default class ContentLayout extends LightningElement {
                     docHeadingEl.style.scrollMarginTop = `${
                         globalNavHeight +
                         docHeaderHeight +
-                        docPhaseEl.offsetHeight
+                        docPhaseEl.getBoundingClientRect().height
                     }px`;
                 });
 
@@ -262,7 +262,7 @@ export default class ContentLayout extends LightningElement {
                     rightNavBarEl.style.top = `${
                         globalNavHeight +
                         docHeaderHeight +
-                        docPhaseEl.offsetHeight
+                        docPhaseEl.getBoundingClientRect().height
                     }px`;
                 }
             }
@@ -280,15 +280,25 @@ export default class ContentLayout extends LightningElement {
             return;
         }
         this.disconnectObserver();
-        this.observer = new IntersectionObserver((entries) => {
-            entries.forEach(
-                (entry) =>
-                    (this.anchoredElements[
-                        entry.target.getAttribute("id")
-                    ].intersect = entry.isIntersecting)
-            );
-            this.calculateActualSection();
-        });
+
+        const globalNavOffset = `-${getComputedStyle(
+            document.documentElement
+        ).getPropertyValue("--dx-g-doc-header-main-nav-height")}`;
+
+        this.observer = new IntersectionObserver(
+            (entries) => {
+                entries.forEach(
+                    (entry) =>
+                        (this.anchoredElements[
+                            entry.target.getAttribute("id")
+                        ].intersect = entry.isIntersecting)
+                );
+                this.calculateActualSection();
+            },
+            {
+                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 = document.querySelectorAll(TOC_HEADER_TAG);
@@ -307,10 +317,6 @@ export default class ContentLayout extends LightningElement {
         }
     };
 
-    onSidebarClick() {
-        this.resetScrollThreshold();
-    }
-
     onSlotChange(event: Event): void {
         const slotElements = (
             event.target as HTMLSlotElement
@@ -366,15 +372,52 @@ export default class ContentLayout extends LightningElement {
         let { hash } = window.location;
         if (hash) {
             hash = hash.substr(1);
+
+            const docHeaderEl = document.querySelector(
+                ".sticky-doc-header"
+            ) as HTMLElement;
+            const globalNavEl = document.querySelector(
+                "hgf-c360nav"
+            ) as HTMLElement;
+            const contextNavEl = document.querySelector(
+                "hgf-c360contextnav"
+            ) as HTMLElement;
+
+            const headerHeight =
+                docHeaderEl.offsetHeight +
+                globalNavEl.offsetHeight +
+                contextNavEl.offsetHeight;
+
+            const docPhaseEl = this.template
+                .querySelector("[name=doc-phase]")!
+                .assignedElements()[0] as HTMLSlotElement;
+
+            const offset = docPhaseEl
+                ? headerHeight + docPhaseEl.offsetHeight
+                : headerHeight;
+
             for (const headingElement of headingElements) {
                 if (headingElement.getAttribute("id") === hash) {
-                    headingElement.scrollIntoView({ behavior: "auto" });
+                    this.scrollIntoViewWithOffset(headingElement, offset);
                     break;
                 }
             }
         }
     }
 
+    private scrollIntoViewWithOffset(
+        headingElement: HTMLElement,
+        offset: number
+    ) {
+        window.scrollTo({
+            behavior: "auto",
+            top:
+                headingElement.getBoundingClientRect().top -
+                document.body.getBoundingClientRect().top -
+                offset
+        });
+    }
+
     private calculateActualSection(): void {
         const currentScrollPosition = document.documentElement.scrollTop;
         const id = Object.keys(this.anchoredElements).find(

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

@@ -62,6 +62,11 @@ dx-button {
     color: var(--dx-g-blue-vibrant-50);
 }
 
+.dismissible-icon {
+    margin-left: auto;
+    cursor: pointer;
+}
+
 /* Small Devices */
 @media screen and (max-width: 480px) {
     .doc-phase-container {

package/src/modules/doc/phase/phase.html

@@ -3,7 +3,7 @@
         <div class="doc-phase-title-container">
             <dx-icon
                 class="doc-status-icon doc-phase-icon"
-                symbol="recipe"
+                symbol={iconName}
                 size="large"
                 color="status-icon-color"
             ></dx-icon>
@@ -11,12 +11,21 @@
                 {docPhaseTitle}
             </p>
             <dx-button
+                if:false={dismissible}
                 variant="inline"
-                onclick={onButtonClick}
+                onclick={onShowHide}
                 aria-label={hideBodyText}
             >
                 {hideBodyText}
             </dx-button>
+            <dx-icon
+                class="dismissible-icon"
+                onclick={onDismiss}
+                if:true={dismissible}
+                symbol="close"
+                size="large"
+                color="status-icon-color"
+            ></dx-icon>
         </div>
         <!--
             NOTE: Here we are rendering mark up using lwc:dom & innerHTML

package/src/modules/doc/phase/phase.ts

@@ -2,16 +2,12 @@ import { LightningElement, api } from "lwc";
 import cx from "classnames";
 
 import { DocPhaseInfo } from "typings/custom";
-import { toJson } from "dxUtils/normalizers";
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 
 export default class Phase extends LightningElement {
     _docPhaseInfo: DocPhaseInfo | null = null;
-
-    isBodyHidden = false;
-
-    get docPhaseTitle() {
-        return this.docPhaseInfo?.title;
-    }
+    _dismissible = false;
+    _iconName = "recipe";
 
     @api
     get docPhaseInfo(): DocPhaseInfo | null {
@@ -22,6 +18,34 @@ export default class Phase extends LightningElement {
         this._docPhaseInfo = toJson(value);
     }
 
+    @api
+    get dismissible(): boolean {
+        return this._dismissible;
+    }
+
+    set dismissible(value) {
+        if (value) {
+            this._dismissible = normalizeBoolean(value);
+        }
+    }
+
+    @api
+    get iconName(): string {
+        return this._iconName;
+    }
+
+    set iconName(value) {
+        if (value) {
+            this._iconName = value;
+        }
+    }
+
+    isBodyHidden = false;
+
+    get docPhaseTitle() {
+        return this.docPhaseInfo?.title;
+    }
+
     get hideBodyText() {
         return this.isBodyHidden ? "Show" : "Hide";
     }
@@ -51,7 +75,19 @@ export default class Phase extends LightningElement {
         }
     }
 
-    onButtonClick() {
+    onShowHide() {
         this.isBodyHidden = !this.isBodyHidden;
     }
+
+    onDismiss() {
+        this.dispatchEvent(
+            new CustomEvent("dismissphase", {
+                detail: {
+                    docPhaseInfo: this.docPhaseInfo
+                },
+                composed: true,
+                bubbles: true
+            })
+        );
+    }
 }

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

@@ -35,6 +35,9 @@ type DropdownOption = {
 export type DocVersion = DropdownOption & {
     releaseVersion: string;
     url: string;
+    link?: {
+        href: string;
+    };
 };
 
 export type DocLanguage = DropdownOption & {

package/src/modules/doc/xmlContent/xmlContent.css

@@ -44,3 +44,9 @@ dx-dropdown > dx-button:hover {
     margin-left: auto;
     margin-right: var(--dx-g-spacing-sm);
 }
+
+doc-phase {
+    --doc-c-phase-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
+    );
+}

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

@@ -11,6 +11,14 @@
         onselect={handleSelect}
         use-old-sidebar={useOldSidebar}
     >
+        <doc-phase
+            slot="version-banner"
+            if:true={showVersionBanner}
+            doc-phase-info={oldVersionInfo}
+            icon-name="warning"
+            dismissible="true"
+            ondismissphase={handleDismissVersionBanner}
+        ></doc-phase>
         <div slot="sidebar-header" class="document-pickers">
             <dx-dropdown
                 data-type="version"

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

@@ -14,7 +14,8 @@ import {
 } from "./types";
 import { SearchSyncer } from "docUtils/SearchSyncer";
 import { LightningElementWithState } from "docBaseElements/lightningElementWithState";
-import { Breadcrumb, Language } from "typings/custom";
+import { oldVersionDocInfo } from "docUtils/utils";
+import { Breadcrumb, DocPhaseInfo, Language } from "typings/custom";
 
 // TODO: Imitating from actual implementation as doc-content use it like this. We should refactor it later.
 const handleContentError = (error): void => console.log(error);
@@ -108,6 +109,33 @@ export default class DocXmlContent extends LightningElementWithState<{
     });
     private _allLanguages: Array<Language> = [];
 
+    private get oldVersionInfo(): DocPhaseInfo | null {
+        let info = null;
+        if (!this.disableVersion) {
+            const currentGAVersion = this.versionOptions.find(
+                (version) => !version.url.includes(version.id)
+            );
+            if (currentGAVersion?.link?.href && this.version?.id) {
+                const versionNo = currentGAVersion.id;
+                /**
+                 * Need to show old version doc banner only if the version is less than the current ga version
+                 * We should not show it to the preview version whose version is more than ga
+                 **/
+                try {
+                    if (parseFloat(this.version.id) < parseFloat(versionNo)) {
+                        info = oldVersionDocInfo(currentGAVersion.link.href);
+                    }
+                } catch (exception) {
+                    /* Ideally this use case should not happen, but just added to not to break the page*/
+                    console.warn(exception);
+                }
+            }
+        }
+        return info;
+    }
+
+    @track showVersionBanner = false;
+
     @track private pageReference: PageReference = {};
     @track breadcrumbs: Array<Breadcrumb> = [];
 
@@ -293,6 +321,10 @@ export default class DocXmlContent extends LightningElementWithState<{
     private handlePopState = (event: PopStateEvent): void =>
         this.updatePageReference(this.getReferenceFromUrl(), event);
 
+    handleDismissVersionBanner() {
+        this.showVersionBanner = false;
+    }
+
     handleSelect(event: CustomEvent<{ name: string }>): void {
         event.stopPropagation();
         const { name } = event.detail;
@@ -424,6 +456,10 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.updateUrl(HistoryState.REPLACE_STATE);
         }
 
+        if (this.oldVersionInfo) {
+            this.showVersionBanner = true;
+        }
+
         if (
             this.pageReference?.contentDocumentId?.replace(/\.htm$/, "") !==
             data.id

package/src/modules/docUtils/utils/utils.ts

@@ -0,0 +1,7 @@
+export const oldVersionDocInfo = (latestVersionLink: string) => {
+    return {
+        title: "Newer Version Available",
+        body: `This content describes an older version of this product. 
+        <a style="font-weight: bold;" href="${latestVersionLink}">View Latest</a>`
+    };
+};