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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.28.5-redoc-alpha",
+  "version": "1.28.5-redoc-alpha2",
   "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 {
@@ -500,32 +533,32 @@ export default class AmfReference extends LightningElement {
         for (const [index, amfConfig] of this._amfConfigList.entries()) {
             let navItemChildren = [] as ParsedMarkdownTopic[];
             let isChildrenLoading = false;
-            if (amfConfig.renderWith === RENDER_WITH.redoc) {
-                // Redoc-rendered specs have no AMF model and no sub-tree; they
-                // appear as leaf items in the sidebar and open the Redoc UI on
-                // selection.
-            } else if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
-                if (amfConfig.isSelected) {
-                    const amfPromise = this.fetchAmf(amfConfig).then(
-                        (amfJson) => {
-                            this.updateModel(amfConfig.id, amfJson);
-                            this.assignNavigationItemsFromAmf(amfConfig, index);
-                        }
-                    );
-                    this.amfFetchPromiseMap[amfConfig.id] = amfPromise;
-                }
-                isChildrenLoading = true;
-            } else {
-                const isExpandChildrenEnabled = this.isExpandChildrenEnabled(
-                    amfConfig.id
-                );
-                // check whether we should expand all the child nodes, this is required for Coveo to crawl.
-                if (isExpandChildrenEnabled) {
-                    this.expandChildrenForMarkdownReferences(
-                        amfConfig.topic!.children
-                    );
+            if (amfConfig.renderWith !== RENDER_WITH.redoc) {
+                if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+                    if (amfConfig.isSelected) {
+                        const amfPromise = this.fetchAmf(amfConfig).then(
+                            (amfJson) => {
+                                this.updateModel(amfConfig.id, amfJson);
+                                this.assignNavigationItemsFromAmf(
+                                    amfConfig,
+                                    index
+                                );
+                            }
+                        );
+                        this.amfFetchPromiseMap[amfConfig.id] = amfPromise;
+                    }
+                    isChildrenLoading = true;
+                } else {
+                    const isExpandChildrenEnabled =
+                        this.isExpandChildrenEnabled(amfConfig.id);
+                    // check whether we should expand all the child nodes, this is required for Coveo to crawl.
+                    if (isExpandChildrenEnabled) {
+                        this.expandChildrenForMarkdownReferences(
+                            amfConfig.topic!.children
+                        );
+                    }
+                    navItemChildren = amfConfig.topic!.children;
                 }
-                navItemChildren = amfConfig.topic!.children;
             }
             // store nav items for each spec in order
             navAmfOrder[index] = {
@@ -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/amfReference/types.ts

@@ -80,15 +80,12 @@ export interface AmfConfig {
     topic?: ParsedMarkdownTopic;
 
     /**
-     * Optional renderer override sent by the backend.
-     * When "redoc", spec-based references are rendered with Redoc instead of
-     * the AMF-based topic view. Other values fall back to the default pipeline.
+     * Required for rendering the arrow on LNB
      */
     renderWith?: string;
 
     /**
-     * Spec URL consumed by alternate renderers (e.g. Redoc). For redoc-rendered
-     * references this is the OpenAPI document URL.
+     * Spec URL consumed by alternate renderers (e.g. Redoc, Mulesoft).
      */
     source?: string;
 }

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";
@@ -14,11 +15,19 @@ declare global {
 
 declare const Sprig: (eventType: string, eventName: string) => void;
 
+type ReferenceTopic = {
+    link?: { href?: string };
+    children?: ReferenceTopic[];
+};
+
 type ReferenceItem = {
     source: string;
     href: string;
+    title?: string;
     isSelected?: boolean;
     docPhase?: string | null;
+    referenceType?: string;
+    topic?: ReferenceTopic;
 };
 
 type ReferenceConfig = {
@@ -77,21 +86,34 @@ 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 {
+        return this._specTitle;
+    }
 
+    set specTitle(value: string | null) {
+        this._specTitle = value || this.getSelectedReference()?.title || null;
+    }
+
+    /**
+     * 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);
     }
 
     /**
-     * Navigates back to the previous history entry when the user clicks the
-     * project-title back link rendered above the Redoc UI.
+     * Navigates back to reference doc.
      */
-    private onBackClick(event: Event): void {
+    private onBackClick = (event: Event): void => {
         event.preventDefault();
         window.history.back();
-    }
+    };
 
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
@@ -332,6 +354,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 +369,74 @@ 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;
+        }
+
+        for (const selector of [".menu-content", ".api-content"]) {
+            const target = redocContainer.querySelector<HTMLElement>(selector);
+            if (
+                !target ||
+                target.querySelector(":scope > .redoc-project-header")
+            ) {
+                continue;
+            }
+            target.insertBefore(
+                this.buildProjectHeaderDom(),
+                target.firstChild
+            );
+        }
+    }
+
+    /**
+     * Builds a fresh project-title/spec-title header DOM node.
+     */
+    private buildProjectHeaderDom(): HTMLElement {
+        const wrapper = document.createElement("div");
+        wrapper.className = "redoc-project-header";
+
+        /* TODO:
+         * Uncomment when doc-header is dropped with Vision state UX.
+         * if(this.projectTitle) {
+         */
+        if (this.specTitle) {
+            const backLink = document.createElement("a");
+            backLink.className = "redoc-project-back";
+            backLink.href = "#";
+            backLink.addEventListener("click", this.onBackClick);
+
+            const icon = createElement("dx-icon", { is: DxIcon });
+            Object.assign(icon, {
+                sprite: "utility",
+                symbol: "back",
+                size: "medium"
+            });
+            icon.classList.add("redoc-project-back-arrow");
+
+            const label = document.createElement("span");
+            label.className = "redoc-project-title";
+            label.textContent = this.specTitle;
+
+            backLink.appendChild(icon);
+            backLink.appendChild(label);
+            wrapper.appendChild(backLink);
+        }
+
+        // TODO: Uncomment when we we have vision state UX with no doc-header
+        // 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