@salesforcedevs/docs-components 1.34.0-alpha2 → 1.34.0-banner-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.34.0-alpha2",
+  "version": "1.34.0-banner-alpha",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",

package/src/modules/doc/redocReference/redocReference.ts

@@ -9,7 +9,8 @@ import SprigSurvey from "doc/sprigSurvey";
 import { throttle } from "throttle-debounce";
 import { pollUntil } from "dxUtils/async";
 import { toJson } from "dxUtils/normalizers";
-import type { OptionWithLink } from "typings/custom";
+import { oldVersionDocInfo } from "docUtils/utils";
+import type { DocPhaseInfo, OptionWithLink } from "typings/custom";
 
 declare global {
     interface Window {
@@ -185,6 +186,14 @@ export default class RedocReference extends LightningElement {
         return this.versions.length > 0;
     }
 
+    /** "Newer version available" banner info when on a non-latest version, else null. */
+    private get oldVersionInfo(): DocPhaseInfo | null {
+        if (this.versions.length > 1 && !this.latestVersion) {
+            return oldVersionDocInfo(this.versions[0].link.href);
+        }
+        return null;
+    }
+
     /** A single version has nothing to choose, so it renders read-only. */
     get isVersionReadOnly(): boolean {
         return this.versions.length === 1;
@@ -586,10 +595,7 @@ export default class RedocReference extends LightningElement {
             const apiContentDiv = await this.waitForApiContent(redocContainer);
             apiContentDiv.setAttribute("lwc:dom", "manual");
 
-            const docPhaseInfo = this.getDocPhaseInfo();
-            if (docPhaseInfo) {
-                this.insertDocPhase(apiContentDiv, docPhaseInfo);
-            }
+            this.insertStatusItems(apiContentDiv);
 
             this.appendFooterItems(apiContentDiv);
 
@@ -780,15 +786,40 @@ export default class RedocReference extends LightningElement {
         return container.querySelector<HTMLElement>(".api-content")!;
     }
 
-    // Creates and inserts doc phase component at container start
-    private insertDocPhase(container: HTMLElement, docPhaseInfo: string): void {
+    // Inserts the doc phase and, on a non-latest version, a dismissible
+    // "newer version" banner into a shared doc-phase-wrapper at container start
+    private insertStatusItems(container: HTMLElement): void {
+        const docPhaseInfo = this.getDocPhaseInfo();
+        const oldVersionInfo = this.oldVersionInfo;
+        if (!docPhaseInfo && !oldVersionInfo) {
+            return;
+        }
+
         const wrapper = document.createElement("div");
         wrapper.className = "doc-phase-wrapper";
         container.insertBefore(wrapper, container.firstChild);
 
-        const docPhaseElement = createElement("doc-phase", { is: DocPhase });
-        Object.assign(docPhaseElement, { docPhaseInfo });
-        wrapper.appendChild(docPhaseElement);
+        if (docPhaseInfo) {
+            const docPhaseElement = createElement("doc-phase", {
+                is: DocPhase
+            });
+            Object.assign(docPhaseElement, { docPhaseInfo });
+            wrapper.appendChild(docPhaseElement);
+        }
+
+        if (oldVersionInfo) {
+            const versionBanner = createElement("doc-phase", { is: DocPhase });
+            Object.assign(versionBanner, {
+                docPhaseInfo: oldVersionInfo,
+                dismissible: true,
+                iconName: "warning"
+            });
+            versionBanner.addEventListener("dismissphase", () => {
+                versionBanner.remove();
+                this.updateSidebarPosition();
+            });
+            wrapper.appendChild(versionBanner);
+        }
     }
 
     // Appends footer component to container

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.html

@@ -24,6 +24,14 @@
             lwc:if={docPhaseInfo}
             doc-phase-info={docPhaseInfo}
         ></doc-phase>
+        <doc-phase
+            slot="version-banner"
+            lwc:if={showVersionBanner}
+            doc-phase-info={oldVersionInfo}
+            icon-name="warning"
+            dismissible="true"
+            ondismissphase={handleDismissVersionBanner}
+        ></doc-phase>
         <slot></slot>
     </doc-content-layout>
 </template>

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.ts

@@ -1,6 +1,12 @@
-import { LightningElement, api } from "lwc";
+import { LightningElement, api, track } from "lwc";
 import { toJson } from "dxUtils/normalizers";
-import type { OptionWithLink, TreeNode } from "typings/custom";
+import type { VersionedNode } from "dxUtils/topicVersion";
+import {
+    findTopicVersionForCurrentPage,
+    latestHrefForCurrentPage
+} from "dxUtils/topicVersion";
+import { oldVersionDocInfo } from "docUtils/utils";
+import type { DocPhaseInfo, OptionWithLink, TreeNode } from "typings/custom";
 
 /**
  * Per-topic type emitted by the docs content-type parser
@@ -67,6 +73,9 @@ export default class UnifiedContentLayout extends LightningElement {
 
     private _docPhaseInfo: string | null = null;
     private _sidebarContent: unknown = null;
+    private _oldVersionInfo: DocPhaseInfo | null = null;
+
+    @track showVersionBanner = false;
 
     @api
     get docPhaseInfo(): string | null {
@@ -83,9 +92,40 @@ export default class UnifiedContentLayout extends LightningElement {
     }
 
     set sidebarContent(value: string) {
-        this._sidebarContent = decorateTopicsWithForwardArrow(
-            toJson(value)?.topics
-        );
+        const topics = decorateTopicsWithForwardArrow(toJson(value)?.topics);
+        this._sidebarContent = topics;
+        this.updateTopicVersionBanner(topics as VersionedNode[] | undefined);
+    }
+
+    get oldVersionInfo(): DocPhaseInfo | null {
+        return this._oldVersionInfo;
+    }
+
+    handleDismissVersionBanner(): void {
+        this.showVersionBanner = false;
+    }
+
+    /**
+     * Same banner references use when the reader is on an older version.
+     * Topic versions are not a separate page property: the sidebar tree
+     * carries each version's switching URL, and the current pathname says
+     * which one is open.
+     */
+    private updateTopicVersionBanner(
+        topics: VersionedNode[] | undefined
+    ): void {
+        const match = findTopicVersionForCurrentPage(topics);
+        const latest = match?.node.versions?.[0];
+        const latestHref = latestHrefForCurrentPage(match?.node.versions);
+
+        if (match && latest && match.version.id !== latest.id && latestHref) {
+            this._oldVersionInfo = oldVersionDocInfo(latestHref);
+            this.showVersionBanner = true;
+            return;
+        }
+
+        this._oldVersionInfo = null;
+        this.showVersionBanner = false;
     }
 
     private get enableFooter(): boolean {

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

@@ -1,10 +1,28 @@
 import { CoveoAnalyticsClient } from "coveo.analytics/dist/browser.mjs"; // This fix is required for Node 20 upgrade, so that Coveo analytics is loaded properly by LWR.
 
+// Resolve against the current origin (version links are usually relative) and
+// keep only http/https. Blocks executable schemes like javascript:/data: that
+// would run when the innerHTML-rendered link is clicked
+// encodeURI then keeps the value from breaking out of the href attribute.
+const toSafeHref = (link: string): string => {
+    try {
+        const { protocol } = new URL(link, window.location.origin);
+        if (protocol === "http:" || protocol === "https:") {
+            return encodeURI(link);
+        }
+    } catch {
+        // Fall through to the rejection below.
+    }
+    console.warn(`Blocked unsafe version link: ${link}`);
+    return "#";
+};
+
 export const oldVersionDocInfo = (latestVersionLink: string) => {
+    const safeLink = toSafeHref(latestVersionLink);
     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>`
+        body: `This content describes an older version of this product.
+        <a style="font-weight: bold;" href="${safeLink}">View Latest</a>`
     };
 };