@salesforcedevs/docs-components 1.34.3-fix-alpha → 1.34.3-fix-redoc-topic-v-2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.34.3-fix-alpha",
+  "version": "1.34.3-fix-redoc-topic-v-2",
   "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.3"
 }

package/src/modules/doc/breadcrumbs/breadcrumbs.css

@@ -21,7 +21,6 @@ nav {
 
 dx-dropdown {
     --dx-c-dropdown-option-font-size: var(--dx-g-text-sm);
-    --dx-c-dropdown-option-font-weight: var(--dx-g-font-bold);
     --dx-c-dropdown-option-label-color: var(
         --dx-c-breadcrumbs-breadcrumb-color
     );

package/src/modules/doc/contentActionToolbar/contentActionToolbar.ts

@@ -127,26 +127,26 @@ export default class ContentActionToolbar extends LightningElement {
                     {
                         id: ACTION_COPY_MARKDOWN,
                         label: COPY_MARKDOWN_LABEL,
-                        endIconSprite: "utility",
-                        endIconSymbol: "copy"
+                        iconSprite: "utility",
+                        iconSymbol: "copy"
                     },
                     {
                         id: ACTION_VIEW_MARKDOWN,
                         label: VIEW_MARKDOWN_LABEL,
-                        endIconSprite: "utility",
-                        endIconSymbol: "new_window"
+                        iconSprite: "utility",
+                        iconSymbol: "new_window"
                     },
                     {
                         id: ACTION_COPY_MARKDOWN_URL,
                         label: COPY_MARKDOWN_URL_LABEL,
-                        endIconSprite: "utility",
-                        endIconSymbol: "link"
+                        iconSprite: "utility",
+                        iconSymbol: "link"
                     },
                     ...AI_ASSISTANTS.map(({ action, label }) => ({
                         id: action,
                         label,
-                        endIconSprite: "utility",
-                        endIconSymbol: "new_window"
+                        iconSprite: "utility",
+                        iconSymbol: "new_window"
                     }))
                 ]
             });
@@ -159,14 +159,14 @@ export default class ContentActionToolbar extends LightningElement {
                 {
                     id: ACTION_VIEW_LLMS,
                     label: VIEW_LLMS_LABEL,
-                    endIconSprite: "utility",
-                    endIconSymbol: "new_window"
+                    iconSprite: "utility",
+                    iconSymbol: "new_window"
                 },
                 {
                     id: ACTION_COPY_LLMS_URL,
                     label: COPY_LLMS_URL_LABEL,
-                    endIconSprite: "utility",
-                    endIconSymbol: "link"
+                    iconSprite: "utility",
+                    iconSymbol: "link"
                 }
             ]
         });

package/src/modules/doc/nav/nav.css

@@ -8,7 +8,7 @@
 }
 
 dx-sidebar {
-    --dx-c-sidebar-content-width: unset;
+    --dx-c-sidebar-width: unset;
 
     display: block;
 }

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

@@ -10,6 +10,15 @@ import { throttle } from "throttle-debounce";
 import { pollUntil } from "dxUtils/async";
 import { toJson } from "dxUtils/normalizers";
 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 {
@@ -47,6 +56,8 @@ type ReferenceVersion = {
 type ReferenceConfig = {
     refList: ReferenceItem[];
     versions?: ReferenceVersion[];
+    /** Sidebar topic name. Sidebar stores the selected version under this key. */
+    versionTopicKey?: string;
 };
 
 const SCROLL_THROTTLE_DELAY = 50;
@@ -129,6 +140,30 @@ 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;
+            console.error("Failed to parse parent topic family", error);
+        }
+    }
+
+    get parentTopicFamily(): { topics?: VersionedNode[] } | null {
+        return this._parentTopicFamilyNode
+            ? { topics: [this._parentTopicFamilyNode] }
+            : null;
+    }
+
+    private _parentTopicFamilyNode: VersionedNode | null = null;
+
     @api
     get contentType(): string {
         return this._contentType;
@@ -233,13 +268,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) {
@@ -362,6 +448,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);
     }
@@ -670,6 +763,18 @@ export default class RedocReference extends LightningElement {
         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(

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

@@ -1,12 +1,12 @@
 @import "dxHelpers/reset";
 
-/* The large picker fills its row (the sidebar sets the row padding). The small
-   menu stops at --doc-version-picker-width, which the sidebar sets. */
+/* NOTE: doc-version-picker-width width variable is used by both dx-button and dx-dropdown to maintain a consistent width. */
 :host {
-    display: block;
-
-    /* Menu labels wrap; break long unspaced labels instead of overflowing. */
-    --dx-c-dropdown-option-overflow-wrap: anywhere;
+    --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);
 }
 
@@ -47,31 +47,16 @@
 
 .version-picker-button {
     display: flex;
-    width: 100%;
+    width: var(--doc-version-picker-width, 296px);
 
     --dx-c-button-horizontal-spacing: var(--dx-g-spacing-sm);
-    --dx-c-button-icon-color: var(--dx-g-gray-50);
-
-    /* A real 1px border at rest. Hover and the open menu turn it dark blue and
-       add a 1px inset shadow, so the edge looks 2px without resizing. */
-    --dx-c-button-custom-color: var(--dx-g-gray-10);
-    --dx-c-button-custom-color-hover: var(--dx-g-gray-10);
-    --dx-c-button-custom-background: white;
-    --dx-c-button-custom-background-hover: var(--dx-g-blue-vibrant-95);
-    --dx-c-button-custom-border: var(--dx-g-gray-50);
-    --dx-c-button-custom-border-hover: var(--dx-g-blue-vibrant-20);
-    --dx-c-button-custom-border-shadow-hover: inset 0 0 0 1px
-        var(--dx-g-blue-vibrant-20);
-
-    /* Keyboard focus keeps the 2px edge inside the white band. */
-    --dx-c-button-focus-shadow: inset 0 0 0 1px var(--dx-g-blue-vibrant-20),
-        0 0 0 2px white;
+    --dx-g-button-icon-color: var(--dx-g-gray-50);
 }
 
 .version-picker-button:hover,
 .version-picker-button:focus-within,
 .version-picker-button[aria-expanded="true"] {
-    --dx-c-button-icon-color: var(--dx-g-blue-vibrant-20);
+    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
 }
 
 /**
@@ -83,6 +68,27 @@ dx-button::part(content) {
     overflow: hidden;
 }
 
+/* The border is an inset box-shadow so thickening it on hover/focus doesn't
+   resize the small variant's fit-content box. */
+.version-picker-button::part(container) {
+    background: white;
+    box-shadow: inset 0 0 0 1px var(--dx-g-gray-50);
+    color: var(--dx-g-gray-10);
+}
+
+.version-picker-button::part(container):hover {
+    background: var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
+}
+
+/* aria-expanded keeps the focus ring while the menu is open. */
+.version-picker-button:focus-within::part(container),
+.version-picker-button[aria-expanded="true"]::part(container) {
+    background: var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20), 0 0 0 2px white,
+        0 0 0 4px var(--dx-g-blue-vibrant-60);
+}
+
 .selected-version {
     display: flex;
     flex-direction: row;
@@ -106,11 +112,24 @@ dx-type-badge.not-latest-badge {
  * Small "dot" variant (opt-in via `small`). Additive 
  * ------------------------------------------------------------------ */
 
-/* The small menu hugs its longest label but never grows wider than the sidebar
-   content (--doc-version-picker-width, set by the sidebar). Labels wrap only at
-   that width. The large menu always matches its trigger (width-mode="full"). */
+/* Option padding is sm both axes: the small menu tracks the ~104px trigger, so
+   the default 24px horizontal would crowd the labels. */
 .version-picker-dropdown-small {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-xs);
+    --dx-c-dropdown-option-padding: var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-sm);
+    --dx-c-dropdown-option-border-radius: 0;
+    --dx-c-popover-border: none;
+
+    /* Hug the labels (down to the shortest) but never wider than the ToC
+       content: 296px on desktop, and on the smallest breakpoint the sidebar
+       variable grows with the viewport up to 720px. Long labels wrap inside
+       that cap. */
     --dx-c-dropdown-menu-max-width: var(--doc-version-picker-width, 296px);
+    --dx-c-dropdown-fit-white-space: normal;
+    --dx-c-dropdown-fit-overflow: hidden;
+    --dx-c-dropdown-fit-text-overflow: clip;
+    --dx-c-dropdown-option-overflow-wrap: anywhere;
 }
 
 .version-picker-button-small {
@@ -135,8 +154,7 @@ dx-type-badge.not-latest-badge {
 }
 
 /* width:100% re-ties to the 104px-capped host (container is width:inherit,
-   which copies width but not max-width). Border, fill, and states come from the
-   dx-button hooks on .version-picker-button. */
+   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);
@@ -168,7 +186,7 @@ dx-type-badge.not-latest-badge {
 .version-picker-readonly {
     box-sizing: border-box;
     display: inline-block;
-    width: 100%;
+    width: var(--doc-version-picker-width, 296px);
     height: var(--dx-g-spacing-xl);
     margin: 0;
     padding: 0 var(--dx-g-spacing-sm);

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

@@ -21,7 +21,7 @@
         >
             <dx-button
                 class={triggerClass}
-                variant="custom"
+                variant="tertiary"
                 size="small"
                 font="sans"
                 icon-symbol="chevrondown"