@salesforcedevs/docs-components 1.28.5-redoc-alpha → 1.28.5-redoc-alpha1

package/package.json

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

package/src/modules/doc/amfReference/amfReference.ts

@@ -38,6 +38,7 @@ type NavigationItem = {
     isExpanded: boolean;
     children: ParsedMarkdownTopic[];
     isChildrenLoading: boolean;
+    renderWith?: string;
 };
 
 export default class AmfReference extends LightningElement {
@@ -147,6 +148,19 @@ export default class AmfReference extends LightningElement {
 
         this._amfConfigList = this._referenceSetConfig.refList || [];
 
+        // If the framework didn't tag the reference, infer redoc rendering
+        // from the config shape: spec-based references with no AMF URL are
+        // shipped as raw spec sources for Redoc to render directly.
+        this._amfConfigList.forEach((amfConfig) => {
+            if (
+                !amfConfig.renderWith &&
+                amfConfig.referenceType !== REFERENCE_TYPES.markdown &&
+                !amfConfig.amf
+            ) {
+                amfConfig.renderWith = RENDER_WITH.redoc;
+            }
+        });
+
         this._amfConfigList.forEach((amfConfig) => {
             this._amfConfigMap.set(amfConfig.id, amfConfig);
         });
@@ -252,6 +266,7 @@ export default class AmfReference extends LightningElement {
 
     _boundOnApiNavigationChanged;
     _boundUpdateSelectedItemFromUrlQuery;
+    _boundOnPageShow;
 
     constructor() {
         super();
@@ -260,6 +275,7 @@ export default class AmfReference extends LightningElement {
             this.onApiNavigationChanged.bind(this);
         this._boundUpdateSelectedItemFromUrlQuery =
             this.updateSelectedItemFromUrlQuery.bind(this);
+        this._boundOnPageShow = this.onPageShow.bind(this);
     }
 
     connectedCallback(): void {
@@ -271,6 +287,7 @@ export default class AmfReference extends LightningElement {
             "popstate",
             this._boundUpdateSelectedItemFromUrlQuery
         );
+        window.addEventListener("pageshow", this._boundOnPageShow);
     }
 
     disconnectedCallback(): void {
@@ -282,6 +299,22 @@ export default class AmfReference extends LightningElement {
             "popstate",
             this._boundUpdateSelectedItemFromUrlQuery
         );
+        window.removeEventListener("pageshow", this._boundOnPageShow);
+    }
+
+    /**
+     * On bfcache restore, reset the sidebar selection so the tree re-syncs
+     * its highlighted tile with the current URL.
+     */
+    protected onPageShow(event: PageTransitionEvent): void {
+        if (!event.persisted) {
+            return;
+        }
+        const currentPath = window.location.pathname;
+        this.selectedSidebarValue = "";
+        Promise.resolve().then(() => {
+            this.selectedSidebarValue = currentPath;
+        });
     }
 
     renderedCallback(): void {
@@ -535,7 +568,8 @@ export default class AmfReference extends LightningElement {
                     amfConfig.isSelected ||
                     this.isExpandChildrenEnabled(amfConfig.id),
                 children: navItemChildren,
-                isChildrenLoading
+                isChildrenLoading,
+                renderWith: amfConfig.renderWith
             };
             this.parentReferenceUrls.push(amfConfig.href);
         }

package/src/modules/doc/redocReference/redocReference.css

@@ -5,27 +5,3 @@
             var(--dx-g-spacing-xl)
     );
 }
-
-.redoc-project-header {
-    display: flex;
-    flex-direction: column;
-    gap: var(--dx-g-spacing-2xs);
-    padding: var(--dx-g-spacing-s) var(--dx-g-spacing-m);
-}
-
-.redoc-project-back {
-    display: inline-flex;
-    align-items: center;
-    gap: var(--dx-g-spacing-xs);
-    color: var(--dx-g-blue-vibrant-50);
-    text-decoration: none;
-    width: fit-content;
-}
-
-.redoc-project-back:hover .redoc-project-title {
-    text-decoration: underline;
-}
-
-.redoc-spec-title {
-    margin: 0;
-}

package/src/modules/doc/redocReference/redocReference.html

@@ -8,22 +8,6 @@
         ></dx-error>
     </template>
     <template lwc:else>
-        <div lwc:if={showRedocHeader} class="redoc-project-header">
-            <a
-                lwc:if={projectTitle}
-                class="redoc-project-back"
-                href="#"
-                onclick={onBackClick}
-            >
-                <dx-icon sprite="utility" symbol="back" size="small"></dx-icon>
-                <span class="redoc-project-title dx-text-body-4">
-                    {projectTitle}
-                </span>
-            </a>
-            <h2 lwc:if={specTitle} class="redoc-spec-title dx-text-display-6">
-                {specTitle}
-            </h2>
-        </div>
         <slot></slot>
     </template>
 </template>

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

@@ -2,6 +2,7 @@
 import { createElement, LightningElement, api } from "lwc";
 import DocPhase from "doc/phase";
 import DxFooter from "dx/footer";
+import DxIcon from "dx/icon";
 import SprigSurvey from "doc/sprigSurvey";
 import { throttle } from "throttle-debounce";
 import { pollUntil } from "dxUtils/async";
@@ -17,6 +18,7 @@ declare const Sprig: (eventType: string, eventName: string) => void;
 type ReferenceItem = {
     source: string;
     href: string;
+    title?: string;
     isSelected?: boolean;
     docPhase?: string | null;
 };
@@ -77,11 +79,28 @@ export default class RedocReference extends LightningElement {
      */
     @api projectTitle: string | null = null;
 
+    private _specTitle: string | null = null;
+
     /** Title of the currently selected spec, shown beneath the project title. */
-    @api specTitle: string | null = null;
+    @api
+    get specTitle(): string | null {
+        if (this._specTitle) {
+            return this._specTitle;
+        }
+        return this.getSelectedReference()?.title ?? null;
+    }
 
+    set specTitle(value: string | null) {
+        this._specTitle = value;
+    }
+
+    /**
+     * Whether to show the project header (only for multi-spec reference sets).
+     */
     get showRedocHeader(): boolean {
-        return !!(this.projectTitle || this.specTitle);
+        const refCount = this._referenceConfig?.refList?.length ?? 0;
+        const isMultiSpecSet = refCount > 1;
+        return isMultiSpecSet && !!(this.projectTitle || this.specTitle);
     }
 
     /**
@@ -332,6 +351,9 @@ export default class RedocReference extends LightningElement {
 
             this.appendFooterItems(apiContentDiv);
 
+            // Inject the multi-spec project header into Redoc's left menu only.
+            this.insertProjectHeaderInMenu(redocContainer);
+
             // Wait for footer to be rendered before updating styles
             requestAnimationFrame(() => {
                 this.updateRedocThirdColumnStyle(redocContainer);
@@ -344,6 +366,80 @@ export default class RedocReference extends LightningElement {
         }
     }
 
+    /**
+     * Inserts the project header into Redoc for multi-spec reference sets.
+     */
+    private insertProjectHeaderInMenu(redocContainer: HTMLElement): void {
+        if (!this.showRedocHeader) {
+            return;
+        }
+        const menuContent =
+            redocContainer.querySelector<HTMLElement>(".menu-content");
+        if (
+            menuContent &&
+            !menuContent.querySelector(":scope > .redoc-project-header")
+        ) {
+            menuContent.insertBefore(
+                this.buildProjectHeaderDom(),
+                menuContent.firstChild
+            );
+        }
+
+        const apiContent =
+            redocContainer.querySelector<HTMLElement>(".api-content");
+        if (
+            apiContent &&
+            !apiContent.querySelector(":scope > .redoc-project-header")
+        ) {
+            apiContent.insertBefore(
+                this.buildProjectHeaderDom(),
+                apiContent.firstChild
+            );
+        }
+    }
+
+    /**
+     * Builds a fresh project-title/spec-title header DOM node.
+     */
+    private buildProjectHeaderDom(): HTMLElement {
+        const wrapper = document.createElement("div");
+        wrapper.className = "redoc-project-header";
+
+        if (this.projectTitle) {
+            const backLink = document.createElement("a");
+            backLink.className = "redoc-project-back";
+            backLink.href = "#";
+            backLink.addEventListener("click", (event) => {
+                event.preventDefault();
+                window.history.back();
+            });
+            // 16x16 utility/back icon. dx-icon size="medium" maps to
+            // --dx-g-icon-size-md (16px).
+            const iconEl = createElement("dx-icon", { is: DxIcon });
+            Object.assign(iconEl, {
+                sprite: "utility",
+                symbol: "back",
+                size: "medium"
+            });
+            iconEl.classList.add("redoc-project-back-arrow");
+            const label = document.createElement("span");
+            label.className = "redoc-project-title";
+            label.textContent = this.projectTitle;
+            backLink.appendChild(iconEl);
+            backLink.appendChild(label);
+            wrapper.appendChild(backLink);
+        }
+
+        if (this.specTitle) {
+            const specEl = document.createElement("h2");
+            specEl.className = "redoc-spec-title";
+            specEl.textContent = this.specTitle;
+            wrapper.appendChild(specEl);
+        }
+
+        return wrapper;
+    }
+
     // Waits for Redoc's API content element to be rendered
     private async waitForApiContent(
         container: HTMLElement