@salesforcedevs/docs-components 1.34.0-tlv-alpha → 1.34.1-doc-phase-redoc-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.34.0-tlv-alpha",
+  "version": "1.34.1-doc-phase-redoc-1",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",
@@ -25,5 +25,6 @@
     "@types/lodash.orderby": "4.6.9",
     "@types/lodash.uniqby": "4.7.9"
   },
-  "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
+  "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad",
+  "stableVersion": "1.34.0"
 }

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 (
@@ -469,7 +534,10 @@ export default class RedocReference extends LightningElement {
                     specUrl,
                     {
                         // Dynamic scroll offset to account for headers
-                        scrollYOffset: this.calculateScrollYOffset
+                        scrollYOffset: this.calculateScrollYOffset,
+                        // White LNB via theme (Redoc's styled background
+                        // outranks injected CSS).
+                        theme: { sidebar: { backgroundColor: "white" } }
                     },
                     redocContainer,
                     (error: any) => {
@@ -515,16 +583,16 @@ 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);
 
             // Inject the multi-spec project header into Redoc's left menu only.
             this.insertSidebarNav(redocContainer);
 
+            // Restore the view selected before a version switch, if any.
+            this.restoreSelectedView();
+
             // Wait for footer to be rendered before updating styles
             requestAnimationFrame(() => {
                 this.updateRedocThirdColumnStyle(redocContainer);
@@ -560,6 +628,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 +696,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 +727,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 +765,42 @@ 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 items: HTMLElement[] = [];
+
+        const docPhaseInfo = this.getDocPhaseInfo();
+        if (docPhaseInfo) {
+            const docPhaseElement = createElement("doc-phase", {
+                is: DocPhase
+            });
+            Object.assign(docPhaseElement, { docPhaseInfo });
+            items.push(docPhaseElement);
+        }
+
+        if (this.oldVersionInfo) {
+            const versionBanner = createElement("doc-phase", { is: DocPhase });
+            Object.assign(versionBanner, {
+                docPhaseInfo: this.oldVersionInfo,
+                dismissible: true,
+                iconName: "warning"
+            });
+            versionBanner.addEventListener("dismissphase", () => {
+                versionBanner.remove();
+                this.updateSidebarPosition();
+            });
+            items.push(versionBanner);
+        }
+
+        if (!items.length) {
+            return;
+        }
+
         const wrapper = document.createElement("div");
         wrapper.className = "doc-phase-wrapper";
+        items.forEach((item) => wrapper.appendChild(item));
         container.insertBefore(wrapper, container.firstChild);
-
-        const docPhaseElement = createElement("doc-phase", { is: DocPhase });
-        Object.assign(docPhaseElement, { docPhaseInfo });
-        wrapper.appendChild(docPhaseElement);
     }
 
     // Appends footer component to container

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

@@ -4,26 +4,44 @@
 :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);
 }
 
 .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,
+        8px var(--dx-g-spacing-lg) 8px
+            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)
+    );
 }
 
 .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 +53,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,17 +88,8 @@ 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);
-
-    margin-left: var(--dx-g-spacing-sm);
-}
-
+dx-type-badge.latest-badge,
 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);
-
     margin-left: var(--dx-g-spacing-sm);
 }
 
@@ -67,26 +97,23 @@ dx-type-badge.not-latest-badge {
  * Small "dot" variant (opt-in via `small`). Additive 
  * ------------------------------------------------------------------ */
 
-/* Scoped hooks so the shared dx-popover/dx-dropdown-option keep their defaults. */
+/* 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-lg);
+        var(--dx-g-spacing-sm);
     --dx-c-dropdown-option-border-radius: 0;
     --dx-c-popover-border: none;
-    --dx-c-popover-padding: var(--dx-g-spacing-sm) 0;
 }
 
 .version-picker-button-small {
-    display: flex;
     width: fit-content;
     max-width: 104px;
-    border-radius: var(--dx-g-spacing-xs);
 
     --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: 18px;
-    --dx-g-button-icon-color: var(--dx-g-gray-50);
+    --dx-c-button-line-height: var(--dx-g-spacing-lg);
     --dx-c-button-icon-gap: var(--dx-g-spacing-2xs);
 }
 
@@ -101,43 +128,12 @@ dx-type-badge.not-latest-badge {
     overflow: hidden;
 }
 
-.version-picker-button-small::part(container),
-.version-picker-readonly-small {
-    box-sizing: border-box;
-    height: var(--dx-g-spacing-lg);
-    padding: 0 var(--dx-g-spacing-xs);
-    border-radius: var(--dx-g-spacing-xs);
-}
-
-/* Border is an inset box-shadow, not a real border, so thickening it on
-   hover/focus doesn't widen the fit-content box (no horizontal shift). */
+/* 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% re-ties to the 104px-capped host (container is width:inherit,
-       which copies width but not max-width). */
     width: 100%;
-    background: white;
-    box-shadow: inset 0 0 0 1px var(--dx-g-gray-50);
-    color: var(--dx-g-gray-10);
-}
-
-.version-picker-button-small::part(container):hover {
-    background: var(--dx-g-blue-vibrant-95);
-    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
-}
-
-.version-picker-button-small:hover,
-.version-picker-button-small:focus-within,
-.version-picker-button-small[aria-expanded="true"] {
-    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
-}
-
-/* Also matches aria-expanded so the ring stays while the menu is open (opening
-   moves focus into the menu, which would otherwise drop :focus-within). */
-.version-picker-button-small:focus-within::part(container),
-.version-picker-button-small[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);
+    height: var(--dx-g-spacing-lg);
+    padding: 0 var(--dx-g-spacing-xs);
 }
 
 .selected-version-small {
@@ -161,16 +157,31 @@ dx-type-badge.not-latest-badge {
     background: var(--dx-g-yellow-vibrant-80);
 }
 
-.version-picker-readonly-small {
+/* inline-block (not flex) so the label can truncate; line-height centers it. */
+.version-picker-readonly {
+    box-sizing: border-box;
     display: inline-block;
-    width: fit-content;
-    max-width: 104px;
+    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-xs) /
-        var(--dx-g-spacing-lg) var(--dx-g-font-sans), sans-serif;
+    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,7 +1,11 @@
 <template>
     <div lwc:if={showVersionPicker} class="version-picker-container">
         <!-- Small read-only: plain value, no dropdown -->
-        <p lwc:if={readOnly} class={readOnlyClass}>
+        <p
+            lwc:if={readOnly}
+            class={readOnlyClass}
+            title={selectedVersion.label}
+        >
             {selectedVersion.label}
         </p>
 
@@ -12,14 +16,14 @@
             analytics-event="custEv_docVersionSelect"
             analytics-payload={analyticsPayload}
             value={selectedVersion.id}
-            width={dropdownWidth}
+            full-width="true"
             onchange={onVersionChange}
         >
             <dx-button
                 class={triggerClass}
                 variant="tertiary"
                 size="small"
-                font={triggerFont}
+                font="sans"
                 icon-symbol="chevrondown"
                 icon-size={triggerIconSize}
                 aria-label={triggerAriaLabel}
@@ -30,25 +34,33 @@
                         <template lwc:if={showLatestTag}>
                             <span class={dotClass} aria-hidden="true"></span>
                         </template>
-                        <p class="selected-version-label">
+                        <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">
+                        <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>

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

@@ -83,9 +83,11 @@ export default class VersionPicker extends LightningElement {
         return !this.hideBadge;
     }
 
-    // Read-only currently only has a small-variant style.
     private get readOnlyClass(): string {
-        return "version-picker-readonly-small";
+        return cx(
+            "version-picker-readonly",
+            this.small && "version-picker-readonly-small"
+        );
     }
 
     private get dotClass(): string {
@@ -108,9 +110,7 @@ export default class VersionPicker extends LightningElement {
     }
 
     // --- Per-variant values for the shared dropdown/button markup below. The
-    // small variant opts into extra classes and a compact chevron; the default
-    // returns undefined so those attributes are omitted (keeps default output
-    // unchanged for xmlContent/amfReference).
+    // 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).
@@ -118,10 +118,6 @@ export default class VersionPicker extends LightningElement {
         return this.small ? "version-picker-dropdown-small" : undefined;
     }
 
-    private get dropdownWidth(): string | undefined {
-        return this.small ? undefined : "var(--doc-version-picker-width)";
-    }
-
     private get triggerClass(): string {
         return cx(
             "version-picker-button",
@@ -129,10 +125,6 @@ export default class VersionPicker extends LightningElement {
         );
     }
 
-    private get triggerFont(): string {
-        return this.small ? "sans" : "display";
-    }
-
     private get triggerIconSize(): string {
         return this.small ? "xsmall" : "medium";
     }
@@ -144,10 +136,7 @@ export default class VersionPicker extends LightningElement {
     }
 
     private get selectedVersionClass(): string {
-        return cx(
-            "selected-version",
-            this.small && "selected-version-small"
-        );
+        return cx("selected-version", this.small && "selected-version-small");
     }
 
     private onVersionChange(e: CustomEvent) {