@salesforcedevs/docs-components 1.34.1 → 1.34.3-final-alpha1

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

@@ -4,11 +4,13 @@ import DocPhase from "doc/phase";
 import DxFooter from "dx/footer";
 import DxIcon from "dx/icon";
 import SidebarFooterNav from "dx/sidebarFooterNav";
+import VersionPicker from "doc/versionPicker";
 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 {
@@ -33,8 +35,18 @@ type ReferenceItem = {
     topic?: ReferenceTopic;
 };
 
+/** A selectable spec version. Mirrors `ReferenceVersion` in `doc/amfReference`. */
+type ReferenceVersion = {
+    id: string;
+    label: string;
+    deprecated?: boolean;
+    selected?: boolean;
+    link: { href: string };
+};
+
 type ReferenceConfig = {
     refList: ReferenceItem[];
+    versions?: ReferenceVersion[];
 };
 
 const SCROLL_THROTTLE_DELAY = 50;
@@ -42,6 +54,7 @@ const ELEMENT_TIMEOUT = 10000;
 const ELEMENT_CHECK_INTERVAL = 100;
 const DEFAULT_PROJECT_TITLE = "All Reference";
 const BACK_TARGET_STORAGE_KEY = "redoc-back-target";
+const SELECTED_VIEW_STORAGE_KEY = "redoc-selected-view";
 const DOCS_PATH_SEGMENT = "docs";
 const DEFAULT_LOCALE = "en-us";
 
@@ -152,6 +165,40 @@ export default class RedocReference extends LightningElement {
         return refCount > 1;
     }
 
+    get versions(): ReferenceVersion[] {
+        return this._referenceConfig?.versions ?? [];
+    }
+
+    /** The version flagged `selected`, else the first (the latest/GA version). */
+    get selectedVersion(): ReferenceVersion | null {
+        const versions = this.versions;
+        return versions.find((v) => v.selected) ?? versions[0] ?? null;
+    }
+
+    /** True when the selected version is the latest/GA one (index 0). */
+    get latestVersion(): boolean {
+        return this.versions.length
+            ? this.selectedVersion?.id === this.versions[0].id
+            : false;
+    }
+
+    get hasVersionPicker(): boolean {
+        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;
+    }
+
     // Reads stored back target
     private getBackTargetFromSession(): string | null {
         return sessionStorage.getItem(BACK_TARGET_STORAGE_KEY);
@@ -202,7 +249,9 @@ export default class RedocReference extends LightningElement {
         }
 
         const referrer = this.getSameOriginReferrerHref();
-        return referrer && !this.isLocaleHref(new URL(referrer).pathname)
+        return referrer &&
+            !this.isLocaleHref(new URL(referrer).pathname) &&
+            !this.isVersionHref(new URL(referrer).pathname)
             ? referrer
             : null;
     }
@@ -241,7 +290,10 @@ export default class RedocReference extends LightningElement {
         }
 
         const referrerUrl = new URL(referrerHref);
-        if (this.isLocaleHref(referrerUrl.pathname)) {
+        if (
+            this.isLocaleHref(referrerUrl.pathname) ||
+            this.isVersionHref(referrerUrl.pathname)
+        ) {
             return;
         }
 
@@ -282,6 +334,19 @@ export default class RedocReference extends LightningElement {
         });
     }
 
+    /**
+     * switching version on this same page.
+     */
+    private isVersionHref(pathname: string): boolean {
+        return this.versions.some((version) => {
+            const href = version?.link?.href;
+            return (
+                !!href &&
+                new URL(href, window.location.origin).pathname === pathname
+            );
+        });
+    }
+
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
         return (
@@ -354,6 +419,14 @@ export default class RedocReference extends LightningElement {
         return parseInt(value, 10) || 0;
     }
 
+    /** Redoc's LNB background color, themeable via `--doc-c-redoc-sidebar-bg`. */
+    private get sidebarBackgroundColor(): string {
+        const value = getComputedStyle(this.template.host).getPropertyValue(
+            "--doc-c-redoc-sidebar-bg"
+        );
+        return value.trim() || "white";
+    }
+
     /*
      ** Since we could not use --dx-g-global-header-height as getPropertyValue returns a calc expression,
      ** we are using the respective CSS variables to calculate the height.
@@ -469,7 +542,14 @@ export default class RedocReference extends LightningElement {
                     specUrl,
                     {
                         // Dynamic scroll offset to account for headers
-                        scrollYOffset: this.calculateScrollYOffset
+                        scrollYOffset: this.calculateScrollYOffset,
+                        // Redoc's own styled background outranks injected
+                        // CSS, so the LNB background must be set via theme.
+                        theme: {
+                            sidebar: {
+                                backgroundColor: this.sidebarBackgroundColor
+                            }
+                        }
                     },
                     redocContainer,
                     (error: any) => {
@@ -515,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);
 
@@ -527,10 +604,22 @@ export default class RedocReference extends LightningElement {
 
             // Wait for footer to be rendered before updating styles
             requestAnimationFrame(() => {
-                this.updateRedocThirdColumnStyle(redocContainer);
-
-                // Fix initial hash scroll after doc phase insertion
-                this.handleInitialHashScrollFix();
+                try {
+                    this.updateRedocThirdColumnStyle(redocContainer);
+
+                    // Restore the view selected before a version switch only
+                    // after all layout mutations (footer, header) are
+                    // complete, so the scroll lands on the correct element.
+                    this.restoreSelectedView();
+
+                    // Fix initial hash scroll after doc phase insertion
+                    this.handleInitialHashScrollFix();
+                } catch (error) {
+                    this.showErrorUI(
+                        "Failed to integrate custom components:",
+                        error
+                    );
+                }
             });
         } catch (error) {
             this.showErrorUI("Failed to integrate custom components:", error);
@@ -560,6 +649,53 @@ export default class RedocReference extends LightningElement {
         }
     }
 
+    /** Builds the version picker DOM by reusing `doc-version-picker`. */
+    private buildVersionPickerDom(): HTMLElement {
+        const wrapper = document.createElement("div");
+        wrapper.className = "redoc-version-picker";
+
+        const picker = createElement("doc-version-picker", {
+            is: VersionPicker
+        });
+
+        Object.assign(picker, {
+            versions: this.versions,
+            selectedVersion: this.selectedVersion,
+            latestVersion: this.latestVersion,
+            readOnly: this.isVersionReadOnly
+        });
+        picker.addEventListener("change", this.onVersionChange);
+        wrapper.appendChild(picker);
+
+        return wrapper;
+    }
+
+    /** Stashes the current view (URL hash) before the version link navigates. */
+    private onVersionChange = (): void => {
+        sessionStorage.setItem(
+            SELECTED_VIEW_STORAGE_KEY,
+            window.location.hash || ""
+        );
+    };
+
+    /**
+     * Re-applies the view stashed before a version switch, if its anchor exists
+     * in the new spec; otherwise a no-op (lands on the spec root).
+     */
+    private restoreSelectedView(): void {
+        const storedHash = sessionStorage.getItem(SELECTED_VIEW_STORAGE_KEY);
+        sessionStorage.removeItem(SELECTED_VIEW_STORAGE_KEY);
+
+        if (!storedHash || window.location.hash) {
+            return;
+        }
+
+        const targetId = storedHash.replace(/^#/, "");
+        if (targetId && document.getElementById(targetId)) {
+            window.location.hash = storedHash;
+        }
+    }
+
     /**
      * Builds the locale picker DOM by reusing `dx-sidebar-footer-nav`
      */
@@ -581,12 +717,17 @@ export default class RedocReference extends LightningElement {
     }
 
     /**
-     * Builds a fresh project-title/spec-title header DOM node.
+     * Builds the doc header: a title group (back link + spec title) and, when
+     * versions are available, the version picker as a sibling row. Layout/gaps
+     * are styled by the developer-website's redoc CSS.
      */
     private buildProjectHeaderDom(): HTMLElement {
         const wrapper = document.createElement("div");
         wrapper.className = "redoc-project-header";
 
+        const main = document.createElement("div");
+        main.className = "redoc-project-header-main";
+
         if (this.projectTitle) {
             const backLink = document.createElement("a");
             backLink.className = "redoc-project-back";
@@ -607,14 +748,20 @@ export default class RedocReference extends LightningElement {
 
             backLink.appendChild(icon);
             backLink.appendChild(label);
-            wrapper.appendChild(backLink);
+            main.appendChild(backLink);
         }
 
         if (this.specTitle) {
             const specEl = document.createElement("h2");
             specEl.className = "redoc-spec-title dx-text-display-7";
             specEl.textContent = this.specTitle;
-            wrapper.appendChild(specEl);
+            main.appendChild(specEl);
+        }
+
+        wrapper.appendChild(main);
+
+        if (this.hasVersionPicker) {
+            wrapper.appendChild(this.buildVersionPickerDom());
         }
 
         return wrapper;
@@ -639,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
@@ -10,61 +16,32 @@ import type { OptionWithLink, TreeNode } from "typings/custom";
  */
 const TOPIC_TYPE_SPEC = "spec";
 
-/**
- * Walks down the first-child chain and returns the first markdown content
- * page found, descending through nested content-less parents. Returns
- * undefined if the chain breaks on a spec or external link before reaching a
- * content page.
- */
-function firstChildContentPage(node: TreeNode): TreeNode | undefined {
-    const firstChild = node.children?.[0];
-    if (!firstChild) {
-        return undefined;
-    }
-
-    const isSpec =
-        (firstChild as { topicType?: string }).topicType === TOPIC_TYPE_SPEC;
-    const isExternal = firstChild.link?.target === "_blank";
-    if (isSpec || isExternal) {
-        return undefined;
-    }
-
-    if (firstChild.link?.href) {
-        return firstChild;
-    }
-
-    return firstChildContentPage(firstChild);
-}
-
 /**
  * Translates per-topic `topicType` into the generic `showForwardArrow` flag
- * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc),
- * and redirects content-less parent topics whose first child is a content page
+ * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc).
+ *
+ * Content-less parents are left without a link. The tree treats them as
+ * parent-only sections and selects the first markdown descendant. Copying that
+ * child's href onto the parent makes the parent win selection.
  */
-function decorateTopics(
-    topics: Array<TreeNode & { topicType?: string }> | undefined
+function decorateTopicsWithForwardArrow(
+    topics:
+        | Array<TreeNode & { topicType?: string; versions?: unknown }>
+        | undefined
 ): TreeNode[] | undefined {
     return topics?.map((topic) => {
-        const { topicType, ...decorated } = topic;
+        const { topicType, versions, ...decorated } = topic;
         if (topicType === TOPIC_TYPE_SPEC) {
             decorated.showForwardArrow = true;
+            // Nested and standalone specs never get a sidebar picker; only the
+            // parent MD topic (when versioned) shows one.
+        } else if (versions) {
+            decorated.versions = versions;
         }
         if (decorated.children) {
-            decorated.children = decorateTopics(decorated.children);
-        }
-
-        /** Redirect a parent that has no content of its own to its first child
-         * but only when that first child is itself a content page
-         */
-        const isContentlessParent =
-            !!decorated.children?.length && !decorated.link?.href;
-
-        if (isContentlessParent) {
-            decorated.redirectToChild = true;
-            const firstChild = firstChildContentPage(topic);
-            if (firstChild?.link) {
-                decorated.link = { ...firstChild.link };
-            }
+            decorated.children = decorateTopicsWithForwardArrow(
+                decorated.children
+            );
         }
 
         return decorated;
@@ -101,6 +78,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 {
@@ -117,7 +97,40 @@ export default class UnifiedContentLayout extends LightningElement {
     }
 
     set sidebarContent(value: string) {
-        this._sidebarContent = decorateTopics(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 {