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

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
@@ -41,16 +47,24 @@ function firstChildContentPage(node: TreeNode): TreeNode | undefined {
  * 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
  */
-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);
+            decorated.children = decorateTopicsWithForwardArrow(
+                decorated.children
+            );
         }
 
         /** Redirect a parent that has no content of its own to its first child
@@ -101,6 +115,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 +134,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 {

package/src/modules/doc/versionPicker/versionPicker.css

@@ -4,26 +4,59 @@
 :host {
     --dx-c-dropdown-option-font-weight: normal;
     --dx-c-dropdown-option-label-color: var(--dx-g-gray-10);
+    --dx-c-dropdown-option-padding: var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-lg);
+    --dx-c-popover-padding: var(--dx-g-spacing-sm) 0;
     --popover-container-open-transform: translateY(4px);
 }
 
+/* Open menus must stack above later sibling pickers in the sidebar. */
+:host(:has([aria-expanded="true"])) {
+    position: relative;
+    z-index: 2;
+}
+
 .version-picker-container {
-    padding: 8px var(--dx-g-spacing-lg) 8px
-        var(--dx-g-global-header-padding-horizontal);
-    border-top: 1px solid var(--dx-g-gray-90);
-    border-bottom: 1px solid var(--dx-g-gray-90);
+    /* Override --doc-version-picker-padding to change the inset (e.g. when the
+       picker sits inside an already-padded container). */
+    padding: var(
+        --doc-version-picker-padding,
+        var(--dx-g-spacing-sm) var(--dx-g-spacing-lg) var(--dx-g-spacing-sm)
+            var(--dx-g-global-header-padding-horizontal)
+    );
+
+    /* Override --doc-version-picker-divider (e.g. `none`) to restyle dividers. */
+    border-top: var(
+        --doc-version-picker-divider,
+        1px solid var(--dx-g-gray-90)
+    );
+    border-bottom: var(
+        --doc-version-picker-divider,
+        1px solid var(--dx-g-gray-90)
+    );
+}
+
+/* Inline sidebar variant: drop the header-slot chrome so the picker sits
+   beside a tree node without extra padding or divider lines. */
+.version-picker-container-small {
+    display: flex;
+    align-items: center;
+    padding: 0;
+    border: none;
 }
 
 .version-picker-button {
     display: flex;
     width: var(--doc-version-picker-width, 296px);
+
+    --dx-c-button-horizontal-spacing: var(--dx-g-spacing-sm);
+    --dx-g-button-icon-color: var(--dx-g-gray-50);
 }
 
 .version-picker-button:hover,
-.version-picker-button:active,
-.version-picker-button:focus {
-    --dx-c-button-secondary-color-hover: var(--dx-g-cloud-blue-vibrant-95);
-    --dx-c-button-primary-color: var(--dx-g-blue-vibrant-40);
+.version-picker-button:focus-within,
+.version-picker-button[aria-expanded="true"] {
+    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
 }
 
 /**
@@ -35,6 +68,27 @@ dx-button::part(content) {
     overflow: hidden;
 }
 
+/* The border is an inset box-shadow so thickening it on hover/focus doesn't
+   resize the small variant's fit-content box. */
+.version-picker-button::part(container) {
+    background: white;
+    box-shadow: inset 0 0 0 1px var(--dx-g-gray-50);
+    color: var(--dx-g-gray-10);
+}
+
+.version-picker-button::part(container):hover {
+    background: var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
+}
+
+/* aria-expanded keeps the focus ring while the menu is open. */
+.version-picker-button:focus-within::part(container),
+.version-picker-button[aria-expanded="true"]::part(container) {
+    background: var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20), 0 0 0 2px white,
+        0 0 0 4px var(--dx-g-blue-vibrant-60);
+}
+
 .selected-version {
     display: flex;
     flex-direction: row;
@@ -49,16 +103,110 @@ dx-button::part(content) {
     white-space: nowrap;
 }
 
-dx-type-badge.latest-badge {
-    --dx-c-type-badge-color: var(--dx-g-green-vibrant-40);
-    --dx-c-type-badge-background: var(--dx-g-green-vibrant-95);
-
+dx-type-badge.latest-badge,
+dx-type-badge.not-latest-badge {
     margin-left: var(--dx-g-spacing-sm);
 }
 
-dx-type-badge.not-latest-badge {
-    --dx-c-type-badge-color: var(--dx-g-red-vibrant-40);
-    --dx-c-type-badge-background: var(--dx-g-red-vibrant-95);
+/* ------------------------------------------------------------------ *
+ * Small "dot" variant (opt-in via `small`). Additive 
+ * ------------------------------------------------------------------ */
 
-    margin-left: var(--dx-g-spacing-sm);
+/* Option padding is sm both axes: the small menu tracks the ~104px trigger, so
+   the default 24px horizontal would crowd the labels. */
+.version-picker-dropdown-small {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-xs);
+    --dx-c-dropdown-option-padding: var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-sm);
+    --dx-c-dropdown-option-border-radius: 0;
+    --dx-c-popover-border: none;
+
+    /* Hug the labels (down to the shortest) but never wider than the ToC
+       content: 296px on desktop, and on the smallest breakpoint the sidebar
+       variable grows with the viewport up to 720px. Long labels wrap inside
+       that cap. */
+    --dx-c-dropdown-menu-max-width: var(--doc-version-picker-width, 296px);
+    --dx-c-dropdown-fit-white-space: normal;
+    --dx-c-dropdown-fit-overflow: hidden;
+    --dx-c-dropdown-fit-text-overflow: clip;
+    --dx-c-dropdown-option-overflow-wrap: anywhere;
+}
+
+.version-picker-button-small {
+    width: fit-content;
+    max-width: 104px;
+
+    --dx-c-button-font-size: var(--dx-g-text-xs);
+    --dx-c-button-font-weight: var(--dx-g-font-normal);
+    --dx-c-button-line-height: var(--dx-g-spacing-lg);
+    --dx-c-button-icon-gap: var(--dx-g-spacing-2xs);
+}
+
+/* min-width: 0 on each flex ancestor lets the label truncate: a flex item's
+   default min-width: auto refuses to shrink below its content and overrides the
+   host's max-width, so without this the trigger overflows instead. */
+.version-picker-button-small::part(content) {
+    display: flex;
+    flex: 1;
+    min-width: 0;
+    width: auto;
+    overflow: hidden;
+}
+
+/* width:100% re-ties to the 104px-capped host (container is width:inherit,
+   which copies width but not max-width). Border/bg/states are shared above. */
+.version-picker-button-small::part(container) {
+    width: 100%;
+    height: var(--dx-g-spacing-lg);
+    padding: 0 var(--dx-g-spacing-xs);
+}
+
+.selected-version-small {
+    flex: 1;
+    min-width: 0;
+}
+
+.version-picker-dot {
+    flex: 0 0 auto;
+    width: var(--dx-g-spacing-sm);
+    height: var(--dx-g-spacing-sm);
+    margin-right: var(--dx-g-spacing-xs);
+    border-radius: 50%;
+}
+
+.version-picker-dot-latest {
+    background: var(--dx-g-green-vibrant-60);
+}
+
+.version-picker-dot-not-latest {
+    background: var(--dx-g-yellow-vibrant-80);
+}
+
+/* inline-block (not flex) so the label can truncate; line-height centers it. */
+.version-picker-readonly {
+    box-sizing: border-box;
+    display: inline-block;
+    width: var(--doc-version-picker-width, 296px);
+    height: var(--dx-g-spacing-xl);
+    margin: 0;
+    padding: 0 var(--dx-g-spacing-sm);
+    border: 1px solid var(--dx-g-gray-80);
+    border-radius: var(--dx-g-spacing-xs);
+    overflow: hidden;
+    color: var(--dx-g-gray-10);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font: var(--dx-g-font-normal) var(--dx-g-text-sm) / var(--dx-g-spacing-xl)
+            var(--dx-g-font-sans),
+        sans-serif;
+}
+
+.version-picker-readonly-small {
+    width: fit-content;
+    max-width: 104px;
+    height: var(--dx-g-spacing-lg);
+    padding: 0 var(--dx-g-spacing-xs);
+    font: var(--dx-g-font-normal) var(--dx-g-text-xs) / var(--dx-g-spacing-lg)
+            var(--dx-g-font-sans),
+        sans-serif;
 }