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

package/package.json

@@ -1,29 +1,29 @@
 {
-    "name": "@salesforcedevs/docs-components",
-    "version": "1.34.3",
-    "description": "Docs Lightning web components for DSC",
-    "license": "MIT",
-    "main": "index.js",
-    "engines": {
-        "node": "22.x"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@api-components/amf-helper-mixin": "4.5.29",
-        "classnames": "2.5.1",
-        "dompurify": "3.2.4",
-        "kagekiri": "1.4.2",
-        "lodash.orderby": "4.6.0",
-        "lodash.uniqby": "4.7.0",
-        "query-string": "7.1.3",
-        "sentence-case": "3.0.4"
-    },
-    "devDependencies": {
-        "@types/classnames": "2.3.1",
-        "@types/lodash.orderby": "4.6.9",
-        "@types/lodash.uniqby": "4.7.9"
-    },
-    "gitHead": "c8c3bb1003d40a55fdd5733c7891dcca3931fb24"
-}
+  "name": "@salesforcedevs/docs-components",
+  "version": "1.34.4-final-alpha1",
+  "description": "Docs Lightning web components for DSC",
+  "license": "MIT",
+  "main": "index.js",
+  "engines": {
+    "node": "22.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@api-components/amf-helper-mixin": "4.5.29",
+    "classnames": "2.5.1",
+    "dompurify": "3.2.4",
+    "kagekiri": "1.4.2",
+    "lodash.orderby": "4.6.0",
+    "lodash.uniqby": "4.7.0",
+    "query-string": "7.1.3",
+    "sentence-case": "3.0.4"
+  },
+  "devDependencies": {
+    "@types/classnames": "2.3.1",
+    "@types/lodash.orderby": "4.6.9",
+    "@types/lodash.uniqby": "4.7.9"
+  },
+  "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
+}

package/src/modules/doc/banner/banner.css

@@ -16,8 +16,6 @@
 }
 
 .icon {
-    --dx-c-icon-size: var(--dx-g-icon-size-lg);
-
     flex-shrink: 0;
     margin-top: var(--dx-g-spacing-smd);
     margin-right: var(--dx-g-spacing-sm);
@@ -73,6 +71,47 @@
     cursor: pointer;
 }
 
+/* Centered variant: the message is centered in the banner and the icon hangs
+   to its left. The close button is taken out of the flow so it doesn't offset
+   the centering. */
+.container_centered {
+    position: relative;
+    display: grid;
+    grid-template-columns: 1fr auto 1fr;
+    align-items: center;
+
+    /* Reserve the close button's width plus its right inset on both sides */
+    padding: 0
+        calc(
+            var(--dx-g-spacing-3xl) + var(--dx-g-spacing-xs) +
+                var(--doc-banner-padding-right)
+        );
+}
+
+.container_centered .icon {
+    grid-column: 1;
+    justify-self: end;
+    margin-top: 0;
+}
+
+.container_centered .main {
+    grid-column: 2;
+    align-items: center;
+    justify-content: center;
+}
+
+.container_centered .message {
+    text-align: center;
+}
+
+.container_centered .close {
+    position: absolute;
+    top: 50%;
+    right: var(--doc-banner-padding-right);
+    margin-left: 0;
+    transform: translateY(-50%);
+}
+
 @media (max-width: 1279px) {
     :host {
         --doc-banner-padding-left: var(--dx-g-spacing-xl);

package/src/modules/doc/banner/banner.html

@@ -1,16 +1,17 @@
 <template>
     <template lwc:if={showBanner}>
-        <div class="container" part="container">
+        <div class={containerClass} part="container">
             <dx-icon
                 class="icon"
-                symbol="info"
-                size="override"
-                color="gray-50"
+                sprite={iconSprite}
+                symbol={iconSymbol}
+                size={iconSize}
+                color={iconColor}
                 part="icon"
             ></dx-icon>
             <div class="main">
                 <div class="message" part="message" lwc:dom="manual"></div>
-                <div class="actions" part="actions">
+                <div lwc:if={hasActions} class="actions" part="actions">
                     <template lwc:if={hasPrimaryButton}>
                         <dx-button
                             href={buttonHref}

package/src/modules/doc/banner/banner.ts

@@ -1,4 +1,6 @@
 import { LightningElement, api } from "lwc";
+import { IconSize, IconSprite, IconSymbol } from "typings/custom";
+import { normalizeBoolean } from "dxUtils/normalizers";
 
 const BANNER_STORAGE_PREFIX = "doc-banner-";
 
@@ -13,6 +15,24 @@ export default class Banner extends LightningElement {
 
     @api dismissStorageKey = "";
 
+    @api
+    get centered(): boolean {
+        return this._centered;
+    }
+    set centered(value: boolean | string) {
+        this._centered = normalizeBoolean(value);
+    }
+
+    @api iconSprite: IconSprite = "utility";
+
+    @api iconSymbol: IconSymbol = "info";
+
+    @api iconColor = "gray-50";
+
+    @api iconSize: IconSize = "large";
+
+    private _centered = false;
+
     private _dismissed = false;
 
     connectedCallback() {
@@ -33,10 +53,18 @@ export default class Banner extends LightningElement {
         }
     }
 
+    get containerClass(): string {
+        return this._centered ? "container container_centered" : "container";
+    }
+
     get showBanner(): boolean {
         return !this._dismissed;
     }
 
+    get hasActions(): boolean {
+        return this.hasPrimaryButton || this.hasSecondaryAction;
+    }
+
     get hasPrimaryButton(): boolean {
         return !!(this.buttonLabel && this.buttonHref);
     }

package/src/modules/doc/redocReference/redocReference.css

@@ -3,4 +3,5 @@
     --doc-c-redoc-sidebar-top: calc(
         var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
     );
+    --doc-c-redoc-sidebar-bg: white;
 }

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

@@ -4,11 +4,22 @@ 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 {
+    applyVersionToHref,
+    collectSubtreeCanonicalHrefs,
+    normalizePath,
+    getTopicVersionKey,
+    persistTopicVersion,
+    toCanonicalHref
+} from "dxUtils/topicVersion";
+import type { VersionedNode } from "dxUtils/topicVersion";
+import type { DocPhaseInfo, OptionWithLink } from "typings/custom";
 
 declare global {
     interface Window {
@@ -33,8 +44,20 @@ 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[];
+    /** Sidebar topic name. Sidebar stores the selected version under this key. */
+    versionTopicKey?: string;
 };
 
 const SCROLL_THROTTLE_DELAY = 50;
@@ -42,6 +65,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";
 
@@ -116,6 +140,29 @@ export default class RedocReference extends LightningElement {
      */
     @api headerHref: string | null = null;
 
+    /**
+     * Versioned topic that owns this spec, including its children.
+     * Href matches this page, so an older version still has its version
+     * in the path.
+     */
+    @api
+    set parentTopicFamily(value: string | { topics?: VersionedNode[] } | null) {
+        try {
+            const parsed = toJson(value) as { topics?: VersionedNode[] } | null;
+            this._parentTopicFamilyNode = parsed?.topics?.[0] ?? null;
+        } catch (error) {
+            this._parentTopicFamilyNode = null;
+        }
+    }
+
+    get parentTopicFamily(): { topics?: VersionedNode[] } | null {
+        return this._parentTopicFamilyNode
+            ? { topics: [this._parentTopicFamilyNode] }
+            : null;
+    }
+
+    private _parentTopicFamilyNode: VersionedNode | null = null;
+
     @api
     get contentType(): string {
         return this._contentType;
@@ -152,6 +199,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);
@@ -186,13 +267,64 @@ export default class RedocReference extends LightningElement {
     private onBackClick = (event: Event): void => {
         event.preventDefault();
 
-        const target = this.getTranslatedBackTarget() ?? this.headerHref;
+        const target = this.getVersionedBackTarget() ?? this.headerHref;
 
         if (target) {
             window.location.assign(target);
         }
     };
 
+    /**
+     * When the back target is in this spec's topic, return it on the
+     * selected version. With no back target, do the same for the header
+     * link when that link is the versioned parent.
+     */
+    private getVersionedBackTarget(): string | null {
+        const stored = this.getTranslatedBackTarget();
+        const selectedVersion = this.selectedVersion;
+        const target = stored ?? this.headerHref;
+        if (!target || !selectedVersion) {
+            return stored;
+        }
+
+        let targetUrl: URL;
+        try {
+            targetUrl = new URL(target, window.location.origin);
+        } catch {
+            return target;
+        }
+
+        // Family hrefs match this page's version. Compare them without
+        // the version segment. Rewrite only the pathname so the target's
+        // query and hash survive.
+        const familyHrefs = this._parentTopicFamilyNode
+            ? collectSubtreeCanonicalHrefs(this._parentTopicFamilyNode).map(
+                  (href) => toCanonicalHref(href, this.versions)
+              )
+            : [];
+
+        const canonicalTarget = toCanonicalHref(
+            targetUrl.pathname,
+            this.versions
+        );
+        const inFamily = familyHrefs.some(
+            (href) => normalizePath(href) === normalizePath(canonicalTarget)
+        );
+        if (!inFamily) {
+            return target;
+        }
+
+        const versioned = applyVersionToHref(
+            canonicalTarget,
+            selectedVersion,
+            this.versions
+        );
+        if (!versioned) {
+            return target;
+        }
+        return `${versioned}${targetUrl.search}${targetUrl.hash}`;
+    }
+
     private getTranslatedBackTarget(): string | null {
         const stored = this.getBackTargetFromSession();
         if (stored) {
@@ -202,7 +334,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 +375,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 +419,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 (
@@ -297,6 +447,13 @@ export default class RedocReference extends LightningElement {
         // Track the back target, preserving it across locale switches
         this.trackBackTarget();
 
+        // Remember the selected version for the sidebar. Changing version
+        // reloads this page.
+        const topicKey = this.getParentTopicVersionKey();
+        if (topicKey && this.selectedVersion) {
+            persistTopicVersion(topicKey, this.selectedVersion.id);
+        }
+
         window.addEventListener("scroll", this.handleScrollAndResize);
         window.addEventListener("resize", this.handleScrollAndResize);
     }
@@ -354,6 +511,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 +634,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 +687,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 +696,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 +741,65 @@ 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;
+    }
+
+    /**
+     * Key the sidebar uses for this topic's selected version.
+     * Missing `versionTopicKey` returns null so nothing is written.
+     */
+    private getParentTopicVersionKey(): string | null {
+        const versionTopicKey = this._referenceConfig?.versionTopicKey;
+        if (!versionTopicKey) {
+            return null;
+        }
+        return getTopicVersionKey({ name: versionTopicKey }) || null;
+    }
+
+    /** 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 +821,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 +852,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 +890,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,38 @@ 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 flagged with redirectToChild and left without a
+ * link. The tree 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);
+            decorated.children = decorateTopicsWithForwardArrow(
+                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) {
+        // Flag a parent with no page of its own. Leave its link empty so the
+        // child's URL stays indexed to the child.
+        if (!!decorated.children?.length && !decorated.link?.href) {
             decorated.redirectToChild = true;
-            const firstChild = firstChildContentPage(topic);
-            if (firstChild?.link) {
-                decorated.link = { ...firstChild.link };
-            }
         }
 
         return decorated;
@@ -101,6 +84,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 +103,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

@@ -2,28 +2,69 @@
 
 /* NOTE: doc-version-picker-width width variable is used by both dx-button and dx-dropdown to maintain a consistent width. */
 :host {
+    /* Always positioned so the popover's containing block stays the picker.
+       Toggling position with aria-expanded lets the menu jump to the sidebar
+       (top of the ToC) for a frame before LWC hides it. */
+    position: relative;
+
     --dx-c-dropdown-option-font-weight: normal;
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-base);
     --dx-c-dropdown-option-label-color: var(--dx-g-gray-10);
+    --dx-c-dropdown-option-active-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);
+    --dx-c-version-picker-focus-ring: 0 0 0 2px white,
+        0 0 0 4px var(--dx-g-blue-vibrant-60);
+}
+
+/* Open menus must stack above later sibling pickers in the sidebar. */
+:host(:has([aria-expanded="true"])) {
+    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);
+    width: 100%;
+    overflow: visible;
+
+    --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[aria-expanded="true"] {
+    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
 }
 
 /**
@@ -35,6 +76,57 @@ dx-button::part(content) {
     overflow: hidden;
 }
 
+/* Border width stays 1px in every state. Hover, open, and focus paint the
+   2px blue stroke with an inset shadow so the box does not grow.
+   Tertiary's hover border is overridden. */
+.version-picker-button::part(container) {
+    box-sizing: border-box;
+    background: white;
+    border: 1px solid var(--dx-g-gray-50);
+    border-radius: var(--dx-g-spacing-xs);
+    box-shadow: none;
+    color: var(--dx-g-gray-10);
+    outline: none;
+    transition: var(--dx-g-transition-hue-1x), box-shadow 0.15s linear;
+}
+
+/* Hover only (not open): 2px #032D60 on #EEF4FF, no ring.
+   Border color matches the fill so the 1px border does not add a third
+   pixel around the inset stroke.
+   :focus-visible is included so click-open + Escape (which upgrades the
+   trigger to keyboard focus) still looks like hover while the pointer is on
+   the picker. */
+.version-picker-button:hover:not([aria-expanded="true"])::part(container),
+.version-picker-button:hover:not([aria-expanded="true"])::part(
+        container
+    ):focus-visible {
+    background: var(--dx-g-blue-vibrant-95);
+    border: 1px solid var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
+}
+
+/* Open keeps the fill and the 2px stroke. The focus ring is keyboard-only,
+   on the closed picker below. */
+.version-picker-button[aria-expanded="true"]::part(container) {
+    background: var(--dx-g-blue-vibrant-95);
+    border: 1px solid var(--dx-g-blue-vibrant-95);
+    border-radius: var(--dx-g-spacing-xs);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
+}
+
+/* Keyboard focus while closed. */
+.version-picker-button:not([aria-expanded="true"])::part(
+        container
+    ):focus-visible {
+    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
+
+    background: var(--dx-g-blue-vibrant-95);
+    border: 1px solid var(--dx-g-blue-vibrant-95);
+    border-radius: var(--dx-g-spacing-xs);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20),
+        var(--dx-c-version-picker-focus-ring);
+}
+
 .selected-version {
     display: flex;
     flex-direction: row;
@@ -49,16 +141,111 @@ 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);
+/* Menu is capped at the ToC width (296px), not the 104px trigger, so options
+   keep the same 16px / 8px 24px / gray-10 type as the default picker. */
+.version-picker-dropdown-small {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-base);
+    --dx-c-dropdown-option-padding: var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-lg);
+    --dx-c-dropdown-option-label-color: var(--dx-g-gray-10);
+    --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: 100%;
+    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;
 }

package/src/modules/doc/versionPicker/versionPicker.html

@@ -1,37 +1,70 @@
 <template>
-    <div lwc:if={showVersionPicker} class="version-picker-container">
+    <div lwc:if={showVersionPicker} class={containerClass}>
+        <!-- Small read-only: plain value, no dropdown -->
+        <p
+            lwc:if={readOnly}
+            class={readOnlyClass}
+            title={selectedVersion.label}
+        >
+            {selectedVersion.label}
+        </p>
+
         <dx-dropdown
+            lwc:else
+            class={dropdownClass}
             options={versions}
             analytics-event="custEv_docVersionSelect"
             analytics-payload={analyticsPayload}
             value={selectedVersion.id}
-            width="var(--doc-version-picker-width)"
+            width-mode={dropdownWidthMode}
             onchange={onVersionChange}
         >
             <dx-button
-                class="version-picker-button"
+                class={triggerClass}
                 variant="tertiary"
                 size="small"
+                font="sans"
                 icon-symbol="chevrondown"
-                icon-size="medium"
+                icon-size={triggerIconSize}
+                aria-label={triggerAriaLabel}
             >
-                <div class="selected-version">
-                    <p class="selected-version-label">
-                        {selectedVersion.label}
-                    </p>
-                    <template lwc:if={showLatestTag}>
-                        <dx-type-badge
-                            class="latest-badge"
-                            lwc:if={latestVersion}
-                            value="Latest"
-                            size="small"
-                        ></dx-type-badge>
-                        <dx-type-badge
-                            class="not-latest-badge"
-                            lwc:else
-                            value="Not Latest"
-                            size="small"
-                        ></dx-type-badge>
+                <div class={selectedVersionClass}>
+                    <!-- Small: leading colored dot -->
+                    <template lwc:if={small}>
+                        <template lwc:if={showLatestTag}>
+                            <span class={dotClass} aria-hidden="true"></span>
+                        </template>
+                        <p
+                            class="selected-version-label"
+                            title={selectedVersion.label}
+                        >
+                            {selectedVersion.label}
+                        </p>
+                    </template>
+                    <!-- Default: trailing Latest/Not-Latest badge -->
+                    <template lwc:else>
+                        <p
+                            class="selected-version-label"
+                            title={selectedVersion.label}
+                        >
+                            {selectedVersion.label}
+                        </p>
+                        <template lwc:if={showLatestTag}>
+                            <dx-type-badge
+                                class="latest-badge"
+                                lwc:if={latestVersion}
+                                variant="status-success"
+                                value="Latest"
+                                size="small"
+                            ></dx-type-badge>
+                            <dx-type-badge
+                                class="not-latest-badge"
+                                lwc:else
+                                variant="status-warning"
+                                value="Not Latest"
+                                size="small"
+                            ></dx-type-badge>
+                        </template>
                     </template>
                 </div>
             </dx-button>

package/src/modules/doc/versionPicker/versionPicker.ts

@@ -1,4 +1,5 @@
 import { LightningElement, api, track } from "lwc";
+import cx from "classnames";
 
 import { AnalyticsPayload, OptionWithNested } from "typings/custom";
 
@@ -12,6 +13,8 @@ export default class VersionPicker extends LightningElement {
     private _selectedVersion?: OptionWithNested;
     private _latestVersion: boolean = false;
     private _hideBadge: boolean = false;
+    private _small: boolean = false;
+    private _readOnly: boolean = false;
 
     @api
     get versions() {
@@ -51,14 +54,103 @@ export default class VersionPicker extends LightningElement {
         this._hideBadge = normalizeBoolean(value);
     }
 
+    // Opt-in compact "dot" variant (24px, abbreviated label). Off by default so
+    // existing consumers render the default trigger unchanged.
+    @api
+    get small() {
+        return this._small;
+    }
+
+    set small(value) {
+        this._small = normalizeBoolean(value);
+    }
+
+    // Opt-in read-only state: plain value, no dropdown menu.
+    @api
+    get readOnly() {
+        return this._readOnly;
+    }
+
+    set readOnly(value) {
+        this._readOnly = normalizeBoolean(value);
+    }
+
     private get showVersionPicker() {
         return this._versions && this._versions.length !== 0;
     }
 
+    private get containerClass(): string {
+        return this.small
+            ? "version-picker-container-small"
+            : "version-picker-container";
+    }
+
     private get showLatestTag(): boolean {
         return !this.hideBadge;
     }
 
+    private get readOnlyClass(): string {
+        return cx(
+            "version-picker-readonly",
+            this.small && "version-picker-readonly-small"
+        );
+    }
+
+    private get dotClass(): string {
+        return `version-picker-dot ${
+            this.latestVersion
+                ? "version-picker-dot-latest"
+                : "version-picker-dot-not-latest"
+        }`;
+    }
+
+    // Accessible name for the small trigger: includes the latest state so it
+    // isn't conveyed by the dot's color alone (WCAG 1.4.1). Omits the state
+    // when the indicator is hidden.
+    private get smallTriggerAriaLabel(): string {
+        const label = this.selectedVersion?.label ?? "";
+        if (!this.showLatestTag) {
+            return label;
+        }
+        return `${label}, ${this.latestVersion ? "Latest" : "Not Latest"}`;
+    }
+
+    // --- Per-variant values for the shared dropdown/button markup below. The
+    // small variant opts into extra classes and a compact chevron.
+
+    // Not cx(): the default must have NO class attribute (cx returns "", which
+    // would render class="" and break the frozen consumer snapshots).
+    private get dropdownClass(): string | undefined {
+        return this.small ? "version-picker-dropdown-small" : undefined;
+    }
+
+    // "full" matches the trigger (ToC width). "fit-end" sizes to the labels,
+    // caps at the ToC width, and opens inward.
+    private get dropdownWidthMode(): "full" | "fit-end" {
+        return this.small ? "fit-end" : "full";
+    }
+
+    private get triggerClass(): string {
+        return cx(
+            "version-picker-button",
+            this.small && "version-picker-button-small"
+        );
+    }
+
+    private get triggerIconSize(): string {
+        return this.small ? "xsmall" : "medium";
+    }
+
+    // Default returns "" (dx-button's own default) so the trigger's rendered
+    // aria-label is unchanged for the default variant.
+    private get triggerAriaLabel(): string {
+        return this.small ? this.smallTriggerAriaLabel : "";
+    }
+
+    private get selectedVersionClass(): string {
+        return cx("selected-version", this.small && "selected-version-small");
+    }
+
     private onVersionChange(e: CustomEvent) {
         this.dispatchEvent(new CustomEvent("change", { detail: e.detail }));
     }

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>`
     };
 };
 

package/LICENSE

@@ -1,12 +0,0 @@
-Copyright (c) 2020, Salesforce.com, Inc.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.