@salesforcedevs/docs-components 1.34.3-final-alpha1 → 1.34.3-fix-redoc-topic-v-1

package/package.json

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

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,51 @@ 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;
+        }
+
+        // Family hrefs match this page's version. Compare them without
+        // the version segment.
+        const familyHrefs = this._parentTopicFamilyNode
+            ? collectSubtreeCanonicalHrefs(this._parentTopicFamilyNode).map(
+                  (href) => toCanonicalHref(href, this.versions)
+              )
+            : [];
+
+        const canonicalTarget = toCanonicalHref(target, this.versions);
+        const inFamily = familyHrefs.some(
+            (href) => normalizePath(href) === normalizePath(canonicalTarget)
+        );
+        if (!inFamily) {
+            return target;
+        }
+
+        return (
+            applyVersionToHref(
+                canonicalTarget,
+                selectedVersion,
+                this.versions
+            ) ?? target
+        );
+    }
+
     private getTranslatedBackTarget(): string | null {
         const stored = this.getBackTargetFromSession();
         if (stored) {
@@ -362,6 +435,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 +750,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(