@salesforcedevs/docs-components 1.34.0-tlv-alpha → 1.34.1-redoc-ver-picker-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.34.0-tlv-alpha",
+  "version": "1.34.1-redoc-ver-picker-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,6 +4,7 @@ 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";
@@ -33,8 +34,22 @@ type ReferenceItem = {
     topic?: ReferenceTopic;
 };
 
+/**
+ * A selectable spec version. Mirrors `ReferenceVersion` in `doc/amfReference`.
+ * Each version's `link.href` makes the picker's dropdown options navigate
+ * natively.
+ */
+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 +57,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 +168,32 @@ 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;
+    }
+
+    /** 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);
@@ -515,6 +557,9 @@ export default class RedocReference extends LightningElement {
             const apiContentDiv = await this.waitForApiContent(redocContainer);
             apiContentDiv.setAttribute("lwc:dom", "manual");
 
+            // White LNB background + divider between the sidebar and content.
+            this.injectRedocStyles(redocContainer);
+
             const docPhaseInfo = this.getDocPhaseInfo();
             if (docPhaseInfo) {
                 this.insertDocPhase(apiContentDiv, docPhaseInfo);
@@ -525,6 +570,9 @@ export default class RedocReference extends LightningElement {
             // 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);
@@ -553,6 +601,15 @@ export default class RedocReference extends LightningElement {
                 });
         }
 
+        // Version picker, inserted directly above Redoc's built-in search box.
+        if (this.hasVersionPicker) {
+            const menuContent =
+                redocContainer.querySelector<HTMLElement>(".menu-content");
+            if (menuContent) {
+                this.insertVersionPicker(menuContent);
+            }
+        }
+
         // Locale picker
         if (this.hasLocalePicker) {
             const menuContent = redocContainer.querySelector(".menu-content");
@@ -560,6 +617,133 @@ export default class RedocReference extends LightningElement {
         }
     }
 
+    /**
+     * Inserts the version picker into Redoc's left menu, directly above its
+     * built-in search box (per the design). Redoc renders the menu
+     * asynchronously and uses hashed styled-component class names, so we poll
+     * for the search box via a set of stable, semantic selectors and fall back
+     * to prepending if it never appears.
+     */
+    private async insertVersionPicker(menuContent: HTMLElement): Promise<void> {
+        const pickerDom = this.buildVersionPickerDom();
+
+        const found = await pollUntil(
+            () => !!this.findSearchBox(menuContent),
+            ELEMENT_CHECK_INTERVAL,
+            ELEMENT_TIMEOUT
+        );
+
+        const searchBox = found ? this.findSearchBox(menuContent) : null;
+        if (searchBox) {
+            // Insert before the search box's top-level child of `.menu-content`.
+            let topLevelNode: HTMLElement = searchBox;
+            while (
+                topLevelNode.parentElement &&
+                topLevelNode.parentElement !== menuContent
+            ) {
+                topLevelNode = topLevelNode.parentElement;
+            }
+            menuContent.insertBefore(pickerDom, topLevelNode);
+        } else {
+            console.warn(
+                "Redoc search box not found; prepending version picker to menu."
+            );
+            menuContent.insertBefore(pickerDom, menuContent.firstChild);
+        }
+    }
+
+    /** Finds Redoc's search box via stable, semantic selectors. */
+    private findSearchBox(menuContent: HTMLElement): HTMLElement | null {
+        return menuContent.querySelector<HTMLElement>(
+            '[role="search"], .search-input, input[type="search"], input[placeholder*="Search" i]'
+        );
+    }
+
+    /** 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 (Redoc's operation anchor is the URL hash) before
+     * the version link navigates, so `restoreSelectedView` can re-apply it once
+     * the target version has loaded.
+     */
+    private onVersionChange = (): void => {
+        sessionStorage.setItem(
+            SELECTED_VIEW_STORAGE_KEY,
+            window.location.hash || ""
+        );
+    };
+
+    /**
+     * Re-applies the view (operation anchor) that was active before a version
+     * switch. The version link navigates to the target version's root (no
+     * hash), so if a hash was stashed and its target exists in the new spec, we
+     * restore it; `handleInitialHashScrollFix` then corrects the scroll offset.
+     * A missing anchor is 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;
+        }
+    }
+
+    /**
+     * Injects a scoped stylesheet into Redoc's light-DOM container so the LNB
+     * matches the design: white background with a divider between the sidebar
+     * and the main content. Component-scoped CSS can't reach Redoc's light DOM,
+     * hence the injected `<style>`. Guarded against duplicate insertion.
+     *
+     * Also suppresses `doc-version-picker`'s own top/bottom dividers for this
+     * placement — those are sidebar chrome for other consumers, but the design
+     * shows no line between the picker and Redoc's search box. Set via the
+     * picker's `--doc-version-picker-divider` custom property, which inherits
+     * through the shadow boundary.
+     */
+    private injectRedocStyles(redocContainer: HTMLElement): void {
+        if (redocContainer.querySelector("style[data-redoc-reference]")) {
+            return;
+        }
+
+        const style = document.createElement("style");
+        style.setAttribute("data-redoc-reference", "");
+        style.textContent = `
+            .redoc-container .menu-content {
+                background: white;
+                border-right: 1px solid var(--dx-g-gray-90);
+            }
+            .redoc-version-picker {
+                --doc-version-picker-divider: none;
+            }
+        `;
+        redocContainer.appendChild(style);
+    }
+
     /**
      * Builds the locale picker DOM by reusing `dx-sidebar-footer-nav`
      */

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

@@ -4,26 +4,40 @@
 :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);
+
+    /* Consumers can suppress or restyle the dividers via
+       --doc-version-picker-divider (e.g. `none`); defaults to the sidebar rule. */
+    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 +49,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 +84,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 +93,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 +124,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 +153,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) {