@salesforcedevs/docs-components 1.28.5-node22-1 → 1.28.5-redoc-alpha1

package/package.json

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

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

@@ -42,7 +42,18 @@
                 latest-version={latestVersion}
             ></doc-version-picker>
         </div>
-        <template lwc:if={showSpecBasedReference}>
+        <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}>
             <div class="container">
                 <div class="api-documentation">
                     <doc-amf-topic

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

@@ -24,6 +24,7 @@ import {
     NAVIGATION_ITEMS,
     URL_CONFIG,
     REFERENCE_TYPES,
+    RENDER_WITH,
     oldReferenceIdNewReferenceIdMap
 } from "./constants";
 import { restoreScroll } from "dx/scrollManager";
@@ -37,6 +38,7 @@ type NavigationItem = {
     isExpanded: boolean;
     children: ParsedMarkdownTopic[];
     isChildrenLoading: boolean;
+    renderWith?: string;
 };
 
 export default class AmfReference extends LightningElement {
@@ -44,6 +46,12 @@ 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;
@@ -69,7 +77,48 @@ 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);
+        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 ?? "";
     }
 
     @api
@@ -99,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);
         });
@@ -204,6 +266,7 @@ export default class AmfReference extends LightningElement {
 
     _boundOnApiNavigationChanged;
     _boundUpdateSelectedItemFromUrlQuery;
+    _boundOnPageShow;
 
     constructor() {
         super();
@@ -212,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 {
@@ -223,6 +287,7 @@ export default class AmfReference extends LightningElement {
             "popstate",
             this._boundUpdateSelectedItemFromUrlQuery
         );
+        window.addEventListener("pageshow", this._boundOnPageShow);
     }
 
     disconnectedCallback(): void {
@@ -234,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 {
@@ -296,6 +377,16 @@ 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.
@@ -442,7 +533,11 @@ export default class AmfReference extends LightningElement {
         for (const [index, amfConfig] of this._amfConfigList.entries()) {
             let navItemChildren = [] as ParsedMarkdownTopic[];
             let isChildrenLoading = false;
-            if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+            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) => {
@@ -473,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);
         }
@@ -862,6 +958,12 @@ 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);
@@ -896,6 +998,9 @@ export default class AmfReference extends LightningElement {
      * @param event
      */
     protected onApiNavigationChanged(): void {
+        if (this.isRedocReference(this._currentReferenceId)) {
+            return;
+        }
         const specBasedReference = this.isSpecBasedReference(
             this._currentReferenceId
         );
@@ -1165,6 +1270,12 @@ 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,6 +61,10 @@ 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

@@ -78,6 +78,19 @@ export interface AmfConfig {
 
     // required for markdown based references
     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.
+     */
+    renderWith?: string;
+
+    /**
+     * Spec URL consumed by alternate renderers (e.g. Redoc). For redoc-rendered
+     * references this is the OpenAPI document URL.
+     */
+    source?: string;
 }
 
 export interface ParsedTopicModel {

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;
 };
@@ -71,6 +73,45 @@ export default class RedocReference extends LightningElement {
     /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). Passed through to dx-footer. */
     @api origin: string | null = null;
 
+    /**
+     * 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;
+
+    private _specTitle: string | null = null;
+
+    /** Title of the currently selected spec, shown beneath the project title. */
+    @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 {
+        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.
+     */
+    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 {
         return (
@@ -108,7 +149,13 @@ export default class RedocReference extends LightningElement {
     }
 
     private getRedocContainer(): HTMLElement | null {
-        return document.querySelector(".redoc-container");
+        // Prefer the slotted container in the consumer's light DOM so this
+        // component composes inside shadow trees; fall back to a global
+        // `.redoc-container` for legacy page-level integrations.
+        return (
+            this.querySelector<HTMLElement>(".redoc-container") ||
+            document.querySelector<HTMLElement>(".redoc-container")
+        );
     }
 
     private getSelectedReference(): ReferenceItem | null {
@@ -304,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);
@@ -316,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

package/.npmrc

@@ -1 +0,0 @@
-//registry.npmjs.org/:_authToken=${SFDOCS_NPM_AUTH_TOKEN}