@salesforcedevs/docs-components 1.28.5-redoc-alpha3 → 1.28.5-redoc-alpha5

package/package.json

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

package/src/modules/doc/amfReference/amfReference.html

@@ -42,18 +42,7 @@
                 latest-version={latestVersion}
             ></doc-version-picker>
         </div>
-        <template lwc:if={showRedocReference}>
-            <doc-redoc-reference
-                reference-config={redocReferenceConfig}
-                doc-phase-info={docPhaseInfo}
-                project-title={projectTitle}
-                spec-title={redocSpecTitle}
-                origin={origin}
-            >
-                <div class="redoc-container"></div>
-            </doc-redoc-reference>
-        </template>
-        <template lwc:elseif={showSpecBasedReference}>
+        <template lwc:if={showSpecBasedReference}>
             <div class="container">
                 <div class="api-documentation">
                     <doc-amf-topic

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

@@ -24,7 +24,6 @@ import {
     NAVIGATION_ITEMS,
     URL_CONFIG,
     REFERENCE_TYPES,
-    RENDER_WITH,
     oldReferenceIdNewReferenceIdMap
 } from "./constants";
 import { restoreScroll } from "dx/scrollManager";
@@ -46,12 +45,6 @@ export default class AmfReference extends LightningElement {
     /** Optional Twitter "via" handle (e.g. SalesforceDevs) for social share; passed to doc-content-layout. */
     @api twitterVia: string | null = null;
     @api sidebarHeader!: string;
-    /**
-     * Project title shown by `<doc-header>` (as its `subtitle`). Forwarded to
-     * `<doc-redoc-reference>` so it can surface the same project title inside
-     * the Redoc-rendered UI.
-     */
-    @api projectTitle: string | null = null;
     @api tocTitle?: string;
     @api tocOptions?: string;
     @api tocAriaLevel?: string;
@@ -77,48 +70,7 @@ export default class AmfReference extends LightningElement {
      * Gives if the currently selected reference is spec based or not
      */
     get showSpecBasedReference(): boolean {
-        return (
-            this.isSpecBasedReference(this._currentReferenceId) &&
-            !this.showRedocReference
-        );
-    }
-
-    /**
-     * Whether the currently selected reference is rendered with Redoc.
-     * Driven by the backend-supplied `renderWith` attribute on the AmfConfig.
-     */
-    get showRedocReference(): boolean {
-        return this.isRedocReference(this._currentReferenceId);
-    }
-
-    /**
-     * Serialized config consumed by `<doc-redoc-reference>`. Built from the
-     * currently selected redoc reference so Redoc has a single spec to render.
-     */
-    get redocReferenceConfig(): string {
-        const ref = this.getAmfConfigWithId(this._currentReferenceId);
-        if (!ref) {
-            return JSON.stringify({ refList: [] });
-        }
-        return JSON.stringify({
-            refList: [
-                {
-                    source: ref.source || ref.amf || "",
-                    href: ref.href,
-                    isSelected: true,
-                    docPhase: ref.docPhase ?? null
-                }
-            ]
-        });
-    }
-
-    /**
-     * Title of the currently selected spec. Forwarded to `<doc-redoc-reference>`
-     * so it can label the spec inside the Redoc UI.
-     */
-    get redocSpecTitle(): string {
-        const ref = this.getAmfConfigWithId(this._currentReferenceId);
-        return ref?.title ?? "";
+        return this.isSpecBasedReference(this._currentReferenceId);
     }
 
     @api
@@ -148,19 +100,6 @@ 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);
         });
@@ -377,16 +316,6 @@ export default class AmfReference extends LightningElement {
             : false;
     }
 
-    /**
-     * @param referenceId
-     * @returns whether the reference should be rendered with Redoc rather than
-     * the AMF-based topic renderer.
-     */
-    private isRedocReference(referenceId: string): boolean {
-        const selectedReference = this.getAmfConfigWithId(referenceId);
-        return selectedReference?.renderWith === RENDER_WITH.redoc;
-    }
-
     /*
      * Refactor below method when sidebar allows sending extraData along with the name for each item.
      * See if we can refactor the below method using regex.
@@ -533,8 +462,8 @@ 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) {
-                if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+            if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+                if (amfConfig.amf) {
                     if (amfConfig.isSelected) {
                         const amfPromise = this.fetchAmf(amfConfig).then(
                             (amfJson) => {
@@ -548,17 +477,18 @@ export default class AmfReference extends LightningElement {
                         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;
                 }
+            } 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;
             }
             // store nav items for each spec in order
             navAmfOrder[index] = {
@@ -569,13 +499,31 @@ export default class AmfReference extends LightningElement {
                     this.isExpandChildrenEnabled(amfConfig.id),
                 children: navItemChildren,
                 isChildrenLoading,
-                renderWith: amfConfig.renderWith
+                renderWith: this.resolveNavRenderWith(amfConfig)
             };
             this.parentReferenceUrls.push(amfConfig.href);
         }
         this.navigation = navAmfOrder;
     }
 
+    /**
+     * Determines the `renderWith` value forwarded to the sidebar. Honors any
+     * value set on the config; otherwise infers `"redoc"` for non-markdown
+     * references that have no AMF URL (i.e. those rendered by Redoc).
+     */
+    private resolveNavRenderWith(amfConfig: AmfConfig): string | undefined {
+        if (amfConfig.renderWith) {
+            return amfConfig.renderWith;
+        }
+        if (
+            amfConfig.referenceType !== REFERENCE_TYPES.markdown &&
+            !amfConfig.amf
+        ) {
+            return "redoc";
+        }
+        return undefined;
+    }
+
     /**
      * Returns a boolean indicating whether the children should be expanded or not.
      */
@@ -958,12 +906,6 @@ export default class AmfReference extends LightningElement {
         const specBasedReference = this.isSpecBasedReference(
             this._currentReferenceId
         );
-        if (this.isRedocReference(this._currentReferenceId)) {
-            // Redoc reads its own state from referenceConfig + window.location;
-            // no metadata to sync from URL on our side.
-            restoreScroll();
-            return;
-        }
         if (specBasedReference) {
             const currentMeta: RouteMeta | undefined =
                 this.getReferenceMetaInfo(window.location.href);
@@ -998,9 +940,6 @@ export default class AmfReference extends LightningElement {
      * @param event
      */
     protected onApiNavigationChanged(): void {
-        if (this.isRedocReference(this._currentReferenceId)) {
-            return;
-        }
         const specBasedReference = this.isSpecBasedReference(
             this._currentReferenceId
         );
@@ -1270,12 +1209,6 @@ export default class AmfReference extends LightningElement {
         }
 
         const specBasedReference = this.isSpecBasedReference(referenceId);
-        const redocReference = this.isRedocReference(referenceId);
-        if (redocReference) {
-            // Redoc-rendered references have no AMF model; the redoc component
-            // handles its own URL/spec resolution from referenceConfig.
-            return;
-        }
         if (specBasedReference) {
             // Wait till the AMF is loaded.
             this.amfFetchPromiseMap[referenceId].then(() => {

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

@@ -61,10 +61,6 @@ export const REFERENCE_TYPES = {
     oa3: "rest-oa3"
 };
 
-export const RENDER_WITH = {
-    redoc: "redoc"
-};
-
 const oldReferenceIdNewReferenceIdMap: Record<string, string> = {
     "commerce-api-assignments": "assignments",
     "commerce-api-campaigns": "campaigns",

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

@@ -83,11 +83,6 @@ export interface AmfConfig {
      * Required for rendering the arrow on LNB
      */
     renderWith?: string;
-
-    /**
-     * Spec URL consumed by alternate renderers (e.g. Redoc, Mulesoft).
-     */
-    source?: string;
 }
 
 export interface ParsedTopicModel {

package/src/modules/doc/header/header.html

@@ -13,7 +13,6 @@
                         onclick={onLinkClick}
                         class="dev-center-content"
                     >
-                        <dx-icon symbol="back"></dx-icon>
                         <dx-icon
                             class="brand-icon"
                             lwc:if={devCenter.icon}

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

@@ -37,6 +37,7 @@ type ReferenceConfig = {
 const SCROLL_THROTTLE_DELAY = 50;
 const ELEMENT_TIMEOUT = 10000;
 const ELEMENT_CHECK_INTERVAL = 100;
+const REFERENCES_SEGMENT = "/references";
 
 export default class RedocReference extends LightningElement {
     private _referenceConfig: ReferenceConfig = { refList: [] };
@@ -47,6 +48,12 @@ export default class RedocReference extends LightningElement {
     private docPhaseWrapperElement: Element | null = null;
     private lastSidebarTop = 0;
 
+    /**
+     * History length captured at mount (pre-Redoc), used by `onBackClick` to
+     * distinguish in-tab navigation (> 1) from a fresh entry (=== 1).
+     */
+    private initialHistoryLength = 0;
+
     showError = false;
 
     @api
@@ -84,7 +91,7 @@ export default class RedocReference extends LightningElement {
      * Project title (same value passed to `<doc-header>` as `subtitle`). Used
      * inside the Redoc-rendered UI to label the parent project.
      */
-    @api projectTitle: string | null = null;
+    @api projectTitle: string | null = "All Reference";
 
     private _specTitle: string | null = null;
 
@@ -112,9 +119,46 @@ export default class RedocReference extends LightningElement {
      */
     private onBackClick = (event: Event): void => {
         event.preventDefault();
-        window.history.back();
+        if (this.cameFromSameOriginPage()) {
+            window.history.back();
+            return;
+        }
+        const fallbackHref = this.getReferencesRootHref();
+        if (fallbackHref) {
+            window.location.href = fallbackHref;
+        }
     };
 
+    /**
+     * Returns true only when the page was reached via in-tab navigation from
+     * a same-origin page, so `history.back()` is safe to call. Checks both
+     * `initialHistoryLength` and `document.referrer` since neither signal is
+     * reliable on its own.
+     */
+    private cameFromSameOriginPage(): boolean {
+        if (this.initialHistoryLength <= 1 || !document.referrer) {
+            return false;
+        }
+        try {
+            return new URL(document.referrer).origin === window.location.origin;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Derives the project's `.../references` root from the current URL by
+     * trimming any trailing reference id (and deeper segments). Returns null
+     * when the URL doesn't contain a `/references` segment.
+     */
+    private getReferencesRootHref(): string | null {
+        const { pathname } = window.location;
+        const idx = pathname.lastIndexOf(REFERENCES_SEGMENT);
+        return idx === -1
+            ? null
+            : pathname.slice(0, idx + REFERENCES_SEGMENT.length);
+    }
+
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
         return (
@@ -123,6 +167,10 @@ export default class RedocReference extends LightningElement {
     }
 
     connectedCallback(): void {
+        // Snapshot history length before Redoc pushes its own hash entries,
+        // so it reflects real in-tab navigation rather than Redoc's churn.
+        this.initialHistoryLength = window.history.length;
+
         window.addEventListener("scroll", this.handleScrollAndResize);
         window.addEventListener("resize", this.handleScrollAndResize);
     }
@@ -393,11 +441,7 @@ export default class RedocReference extends LightningElement {
         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) {
+        if (this.projectTitle) {
             const backLink = document.createElement("a");
             backLink.className = "redoc-project-back";
             backLink.href = "#";
@@ -413,20 +457,19 @@ export default class RedocReference extends LightningElement {
 
             const label = document.createElement("span");
             label.className = "redoc-project-title";
-            label.textContent = this.specTitle;
+            label.textContent = this.projectTitle;
 
             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);
-        // }
+        if (this.specTitle) {
+            const specEl = document.createElement("h2");
+            specEl.className = "redoc-spec-title dx-text-display-7";
+            specEl.textContent = this.specTitle;
+            wrapper.appendChild(specEl);
+        }
 
         return wrapper;
     }