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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.34.4-final-alpha",
+  "version": "1.34.4-final-alpha1",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",

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,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;
@@ -233,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) {
@@ -362,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);
     }
@@ -670,6 +762,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(